Coder Client

Method reference for CoderClient from the standalone @agentuity/coder package. Coder is not a ctx.* service; the client is used from agents, scripts, or external apps.

Install

bun add @agentuity/coder

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();

Constructor

new CoderClient(options?: CoderClientOptions)

The client resolves the Hub URL in this order:

1. options.url (explicit)
2. AGENTUITY_CODER_URL environment variable
3. Auto-discovery via the Agentuity API

Most apps only need the API key. Set AGENTUITY_SDK_KEY and let the client discover the rest.

Sessions

createSession(body)

Create a new coder session.

Returns: Promise<CoderCreateSessionResponse>

const session = await client.createSession({
  task: 'Implement OAuth login with GitHub provider',
  workflowMode: 'standard',
  tags: ['auth', 'feature'],
});
console.log(session.sessionId);

getSession(sessionId)

Retrieve a session by ID.

Returns: Promise<CoderSession>

const session = await client.getSession('codesess_abc123');

updateSession(sessionId, body)

Update session metadata.

Only the fields above are patchable. Workflow mode, loop configuration, and arbitrary metadata are fixed at session creation.

Returns: Promise<CoderUpdateSessionResponse>

await client.updateSession('codesess_abc123', {
  label: 'Auth feature - phase 2',
  tags: ['auth', 'feature', 'phase-2'],
});

listSessions(params?)

List sessions with optional filtering and pagination.

params fields (all optional):

Returns: Promise<CoderSessionListResponse>

const { sessions, total } = await client.listSessions({ limit: 20 });
for (const s of sessions) {
  console.log(`${s.sessionId}: ${s.label} (${s.status})`);
}

listConnectableSessions(params?)

List sessions the caller can connect to. Archived and history-only sessions are filtered out.

Derived from listSessions() with client-side filtering.

params fields (all optional):

Returns: Promise<CoderSessionListResponse>

deleteSession(sessionId)

Permanently delete a session.

Returns: Promise<void>

await client.deleteSession('codesess_abc123');

archiveSession(sessionId)

Archive an active session. The transcript is preserved for replay.

Returns: Promise<CoderLifecycleResponse>

await client.archiveSession('codesess_abc123');

resumeSession(sessionId)

Wake a paused sandbox session.

Returns: Promise<CoderLifecycleResponse>

await client.resumeSession('codesess_abc123');

prepareSessionForRemoteAttach(sessionId, options?)

Ensure a paused remote session is attachable before opening a controller socket. If the session is history-only, returns immediately. If the session is wakeable and the runtime is unavailable, calls resumeSession and polls getSession until the runtime is back or the timeout elapses.

Returns: Promise<CoderSession> — the latest session detail (which may still be detached if the timeout elapsed)

const session = await client.prepareSessionForRemoteAttach('codesess_abc123', {
  timeoutMs: 60_000,
});
if (session.runtimeAvailable) {
  // Safe to open the controller socket
}

Session Data

getReplay(sessionId, params?)

Retrieve replay data (transcript and events) for a session.

Returns the full replay payload in a single response. For field-level details, see the Coder API reference.

Returns: Promise<CoderSessionReplay>

const replay = await client.getReplay('codesess_abc123');

listParticipants(sessionId, params?)

List participants for a session (primary agents, sub-agents, and observers).

The Hub route supports limit and includeDisconnected. The SDK method exposes limit plus a legacy offset. See the Coder API reference for the full query contract.

Returns: Promise<CoderSessionParticipants>

const { participants } = await client.listParticipants('codesess_abc123');

listEventHistory(sessionId, params?)

List historical events for a session.

The Hub route uses limit and beforeId for pagination. The SDK method still exposes offset for compatibility. See the Coder API reference for the full query contract.

Returns: Promise<CoderSessionEventHistory>

const history = await client.listEventHistory('codesess_abc123', { limit: 50 });

Loop State

getLoopState(sessionId, params?)

Get loop-mode state for an autonomous session. Returns null loop when the session is not in loop mode.

Returns: Promise<CoderLoopStateResponse>

const { loop } = await client.getLoopState('codesess_abc123');
if (loop) {
  console.log(`Status: ${loop.status}, iteration ${loop.iteration}`);
}

The loop state includes status, iteration, maxIterations, goal, summary, nextAction, and timing fields. Status values: idle, starting, running, paused, completed, cancelled, blocked, awaiting_input.

Workspaces

Workspaces group repositories and skills into reusable configurations attachable to sessions.

createWorkspace(body)

Returns: Promise<CoderWorkspaceDetail>

const workspace = await client.createWorkspace({
  name: 'Auth System',
  description: 'OAuth and session management',
});

listWorkspaces()

List all available workspaces.

Returns: Promise<CoderWorkspaceListResponse>

getWorkspace(workspaceId)

Retrieve a workspace by ID.

Returns: Promise<CoderWorkspaceDetail>

deleteWorkspace(workspaceId)

Delete a workspace.

Returns: Promise<void>

Skills

saveSkill(body)

Save a reusable skill to the caller's library.

Returns: Promise<CoderSavedSkill>

const skill = await client.saveSkill({
  repo: 'my-org/my-skills',
  skillId: 'code-review',
  name: 'code-review',
  description: 'Review code for security issues',
  content: 'Review the changes for OWASP top 10 vulnerabilities...',
});

listSavedSkills()

List saved skills in the caller's library.

Returns: Promise<CoderSavedSkillListResponse>

deleteSavedSkill(skillId)

Delete a saved skill.

Returns: Promise<void>

createSkillBucket(body)

Group saved skills into a bucket that can be attached to sessions.

Returns: Promise<CoderSkillBucket>

listSkillBuckets()

List all skill buckets.

Returns: Promise<CoderSkillBucketListResponse>

deleteSkillBucket(bucketId)

Delete a skill bucket.

Returns: Promise<void>

GitHub

listGitHubAccounts()

List GitHub accounts available via the caller's GitHub App installations. The response includes connection status, the connected GitHub username, and all available accounts.

Returns: Promise<CoderGitHubAccountListResponse>

const { connected, accounts } = await client.listGitHubAccounts();
if (!connected) {
  console.log('Connect GitHub first');
}

listGitHubRepos(accountId)

List repositories accessible under a specific GitHub account.

Returns: Promise<CoderGitHubRepositoryListResponse>

const { repositories } = await client.listGitHubRepos('12345');

Users

listUsers(params?)

List known users in the Coder Hub. Supports search and pagination.

params fields (all optional):

Returns: Promise<CoderListUsersResponse>

const { users } = await client.listUsers({ search: 'alice', limit: 10 });

Next Steps

• Coder: Concepts, session lifecycle, and workflow guidance
• @agentuity/coder Package: Install and constructor overview
• Coder CLI Commands: Full agentuity coder command reference