@agent-harbor/rest-client

Shared REST API client for Agent Harbor.

Installation

yarn add @agent-harbor/rest-client

Usage

Creating a Client

import { createApiClient } from '@agent-harbor/rest-client';

// Simple usage with just a base URL
const client = createApiClient('http://localhost:8080/api/v1');

// With custom options
const client = createApiClient({
  baseUrl: 'http://localhost:8080/api/v1',
  headers: {
    Authorization: 'Bearer your-token',
  },
});

Creating a Task

import { createApiClient, CreateTaskRequest } from '@agent-harbor/rest-client';

const client = createApiClient('http://localhost:8080/api/v1');

const taskRequest: CreateTaskRequest = {
  prompt: 'Fix the bug in main.ts',
  repo: {
    mode: 'git',
    url: 'https://github.com/example/repo',
    branch: 'main',
  },
  runtime: {
    type: 'devcontainer',
  },
  agent: {
    type: 'claude-code',
    version: 'latest',
  },
  output: {
    format: 'stream-json',
    flavor: 'ah',
  },
};

const response = await client.createTask(taskRequest);
console.log('Created sessions:', response.session_ids);

Managing Sessions

// List sessions
const sessions = await client.listSessions({ status: 'running' });

// Get a specific session
const session = await client.getSession(sessionId);

// Stop a session gracefully
await client.stopSession(sessionId);

// Cancel a session immediately
await client.cancelSession(sessionId);

// Pause and resume
await client.pauseSession(sessionId);
await client.resumeSession(sessionId);

// Get session logs
const logs = await client.getSessionLogs(sessionId, 100); // Last 100 lines

Error Handling

import { createApiClient, ApiClientError } from '@agent-harbor/rest-client';

const client = createApiClient('http://localhost:8080/api/v1');

try {
  await client.getSession('non-existent-id');
} catch (error) {
  if (error instanceof ApiClientError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.status}`);

    if (error.isNotFound()) {
      console.error('Session not found');
    }

    if (error.hasValidationErrors()) {
      console.error('Validation errors:', error.apiError?.errors);
    }
  }
}

SSE Events (Browser)

For browser environments, you can use the built-in EventSource support:

const eventSource = client.subscribeToSessionEvents(sessionId, event => {
  switch (event.type) {
    case 'status':
      console.log('Status changed:', event.status);
      break;
    case 'tool_execution':
      console.log('Tool executed:', event.tool_name);
      break;
    case 'thinking':
      console.log('Agent thinking:', event.thought);
      break;
  }
});

// Later: close the connection
eventSource.close();

For Node.js environments, use the @agent-harbor/sse-client package for more robust SSE handling.

API Reference

Client Methods

| Method | Description | | --------------------------------------- | -------------------------------------- | | createTask(data) | Create a new task | | listSessions(params?) | List sessions with optional filtering | | getSession(id) | Get a specific session | | stopSession(id) | Stop a session gracefully | | cancelSession(id) | Cancel a session immediately | | pauseSession(id) | Pause a running session | | resumeSession(id) | Resume a paused session | | getSessionLogs(id, tail?) | Get session logs | | sendMessage(id, message) | Send a message to a session | | getSessionEventsUrl(id) | Get SSE events URL | | subscribeToSessionEvents(id, onEvent) | Subscribe to SSE events (browser only) | | listAgents() | List available agent types | | listRuntimes() | List available runtime types | | listRepositories(params?) | List repositories | | getRepository(id) | Get a specific repository | | listDrafts() | List draft tasks | | createDraft(draft) | Create a draft task | | updateDraft(id, updates) | Update a draft task | | deleteDraft(id) | Delete a draft task |

Types

The package exports all types needed for working with the API:

• Configuration: Repository, Runtime, Agent, Delivery, OutputConfig
• Tasks: CreateTaskRequest, CreateTaskResponse
• Sessions: Session, SessionStatus, SessionsListResponse
• Events: SessionEvent, StatusEvent, LogEvent, ThinkingEvent, ToolExecutionEvent, FileEditEvent
• Metadata: AgentType, RuntimeType, RepositoryItem
• Drafts: DraftCreate, DraftTask, DraftUpdate
• Feedback: FeedbackRequest, FeedbackResponse, FeedbackOption
• Errors: ApiError, ApiClientError

License

Apache-2.0