@agentuity/core 2.0.9 → 2.0.11

package/src/services/coder/client.ts

@@ -14,12 +14,22 @@ import {
 	coderGetSession,
 	coderListConnectableSessions,
 	coderListSessions,
+	coderResumeSession,
 	coderUpdateSession,
 	type CoderCreateSessionParams,
 	type CoderUpdateSessionResponse,
 	type CoderListConnectableSessionsParams,
 	type CoderListSessionsParamsWithOrg,
 } from './sessions.ts';
+import {
+	coderArchiveCustomAgent,
+	coderCreateCustomAgent,
+	coderGetCustomAgent,
+	coderListCustomAgents,
+	coderListCustomAgentVersions,
+	coderPublishCustomAgent,
+	coderUpdateCustomAgent,
+} from './agents.ts';
 import {
 	coderCreateSkillBucket,
 	coderDeleteSavedSkill,
@@ -48,6 +58,10 @@ import { coderListUsers, type CoderListUsersParamsWithOrg } from './users.ts';
 import type {
 	CoderGitHubAccountListResponse,
 	CoderGitHubRepositoryListResponse,
+	CoderCustomAgent,
+	CoderCustomAgentListResponse,
+	CoderCustomAgentVersionListResponse,
+	CoderCreateCustomAgentRequest,
 	CoderListUsersResponse,
 	CoderSavedSkill,
 	CoderSavedSkillListResponse,
@@ -60,6 +74,7 @@ import type {
 	CoderSkillBucket,
 	CoderSkillBucketListResponse,
 	CoderCreateSkillBucketRequest,
+	CoderUpdateCustomAgentRequest,
 	CoderCreateWorkspaceRequest,
 	CoderWorkspaceDetail,
 	CoderWorkspaceListResponse,
@@ -71,7 +86,7 @@ import { normalizeCoderUrl } from './util.ts';
 export const CoderClientOptionsSchema = z
 	.object({
 		apiKey: z.string().optional().describe('API key for authentication'),
-		url: z.string().optional().describe('Base URL for the Coder Hub HTTP API'),
+		url: z.string().optional().describe('Base URL for the Coder HTTP API'),
 		region: z.string().optional().describe('Region used for Catalyst URL resolution'),
 		orgId: z.string().optional().describe('Organization ID for multi-tenant operations'),
 		logger: z.custom<Logger>().optional().describe('Custom logger implementation'),
@@ -79,8 +94,13 @@ export const CoderClientOptionsSchema = z
 	.describe('Configuration options for constructing a CoderClient');
 export type CoderClientOptions = z.infer<typeof CoderClientOptionsSchema>;
 
+export interface CoderRemoteAttachPreparationOptions {
+	timeoutMs?: number;
+	pollIntervalMs?: number;
+}
+
 /**
- * Ergonomic client for Coder Hub session management APIs.
+ * Ergonomic client for Coder session management APIs.
  *
  * URL resolution strategy:
  * 1) options.url
@@ -214,6 +234,54 @@ export class CoderClient {
 		return coderArchiveSession(client, { sessionId, orgId: this.#orgId });
 	}
 
+	/**
+	 * Requests that a wakeable sandbox session be resumed.
+	 */
+	async resumeSession(sessionId: string): Promise<CoderLifecycleResponse> {
+		const client = await this.#getClient();
+		return coderResumeSession(client, { sessionId, orgId: this.#orgId });
+	}
+
+	/**
+	 * Makes sure a paused remote session is attachable before opening the controller socket.
+	 */
+	async prepareSessionForRemoteAttach(
+		sessionId: string,
+		options: CoderRemoteAttachPreparationOptions = {}
+	): Promise<CoderSession> {
+		const timeoutMs = options.timeoutMs ?? 30_000;
+		const pollIntervalMs = options.pollIntervalMs ?? 1_000;
+		let session = await this.getSession(sessionId);
+
+		if (session.historyOnly === true) {
+			return session;
+		}
+
+		if (session.wakeAvailable === true && session.runtimeAvailable === false) {
+			await this.resumeSession(sessionId);
+			const deadline = Date.now() + timeoutMs;
+
+			while (Date.now() < deadline) {
+				await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+				try {
+					session = await this.getSession(sessionId);
+				} catch (err) {
+					this.#logger.debug(
+						'coder remote attach poll failed for %s: %s',
+						sessionId,
+						err instanceof Error ? err.message : String(err)
+					);
+					continue;
+				}
+				if (session.historyOnly === true || session.runtimeAvailable !== false) {
+					return session;
+				}
+			}
+		}
+
+		return session;
+	}
+
 	/**
 	 * Lists sessions the caller can connect to.
 	 */
@@ -256,6 +324,69 @@ export class CoderClient {
 		return coderDeleteWorkspace(client, { workspaceId });
 	}
 
+	/**
+	 * Lists custom agents in the org library.
+	 */
+	async listCustomAgents(options?: {
+		includeArchived?: boolean;
+	}): Promise<CoderCustomAgentListResponse> {
+		const client = await this.#getClient();
+		return coderListCustomAgents(client, { ...options, orgId: this.#orgId });
+	}
+
+	/**
+	 * Retrieves a custom agent by id or slug.
+	 */
+	async getCustomAgent(agentIdOrSlug: string): Promise<CoderCustomAgent> {
+		const client = await this.#getClient();
+		return coderGetCustomAgent(client, { agentIdOrSlug, orgId: this.#orgId });
+	}
+
+	/**
+	 * Creates a new custom-agent draft.
+	 */
+	async createCustomAgent(body: CoderCreateCustomAgentRequest): Promise<CoderCustomAgent> {
+		const client = await this.#getClient();
+		return coderCreateCustomAgent(client, { body, orgId: this.#orgId });
+	}
+
+	/**
+	 * Updates an existing custom-agent draft.
+	 */
+	async updateCustomAgent(
+		agentIdOrSlug: string,
+		body: CoderUpdateCustomAgentRequest
+	): Promise<CoderCustomAgent> {
+		const client = await this.#getClient();
+		return coderUpdateCustomAgent(client, { agentIdOrSlug, body, orgId: this.#orgId });
+	}
+
+	/**
+	 * Publishes the latest custom-agent draft as a new immutable version.
+	 */
+	async publishCustomAgent(agentIdOrSlug: string): Promise<CoderCustomAgent> {
+		const client = await this.#getClient();
+		return coderPublishCustomAgent(client, { agentIdOrSlug, orgId: this.#orgId });
+	}
+
+	/**
+	 * Archives a custom agent from the org library.
+	 */
+	async archiveCustomAgent(agentIdOrSlug: string): Promise<CoderCustomAgent> {
+		const client = await this.#getClient();
+		return coderArchiveCustomAgent(client, { agentIdOrSlug, orgId: this.#orgId });
+	}
+
+	/**
+	 * Lists published versions for a custom agent.
+	 */
+	async listCustomAgentVersions(
+		agentIdOrSlug: string
+	): Promise<CoderCustomAgentVersionListResponse> {
+		const client = await this.#getClient();
+		return coderListCustomAgentVersions(client, { agentIdOrSlug, orgId: this.#orgId });
+	}
+
 	/**
 	 * Lists saved skills in the caller's library.
 	 */

package/src/services/coder/close-codes.ts

@@ -0,0 +1,83 @@
+/**
+ * WebSocket close codes for the Coder Hub.
+ *
+ * These codes use the 4xxx private range defined by RFC 6455, allowing
+ * application-specific close reasons that trigger terminal disconnection
+ * (no automatic reconnect).
+ *
+ * @module coder/close-codes
+ *
+ * @example
+ * ```typescript
+ * import { CODER_WS_CLOSE_CODE, isTerminalCloseCode } from '@agentuity/core/coder';
+ *
+ * // Check if a close code is terminal (should not reconnect)
+ * if (isTerminalCloseCode(4401)) {
+ *   console.log('Auth failed, will not reconnect');
+ * }
+ *
+ * // Use close codes when closing connections
+ * client.close(CODER_WS_CLOSE_CODE.AUTH_REQUIRED, 'Invalid API key');
+ * ```
+ */
+
+/**
+ * Application-defined WebSocket close codes for the Coder Hub.
+ *
+ * These codes indicate specific error conditions that should not trigger
+ * automatic reconnection. The 4xxx range is reserved for application use
+ * per RFC 6455.
+ */
+export const CODER_WS_CLOSE_CODE = {
+	/** Invalid request parameters (4000 range equivalent) */
+	BAD_REQUEST: 4400,
+	/** Authentication required or credentials invalid */
+	AUTH_REQUIRED: 4401,
+	/** Authenticated but not authorized for this resource */
+	FORBIDDEN: 4403,
+	/** The requested session does not exist */
+	SESSION_NOT_FOUND: 4404,
+	/** Service temporarily unavailable */
+	UNAVAILABLE: 4408,
+	/** Session already has an active lead connection */
+	SESSION_ACTIVE: 4409,
+	/** Reconnecting driver with stale instance ID */
+	STALE_DRIVER: 4410,
+	/** Rate limit exceeded */
+	RATE_LIMITED: 4429,
+	/** Internal server error */
+	INTERNAL_ERROR: 4500,
+} as const;
+
+/**
+ * Union type of all valid Coder Hub WebSocket close codes.
+ */
+export type CoderWsCloseCode = (typeof CODER_WS_CLOSE_CODE)[keyof typeof CODER_WS_CLOSE_CODE];
+
+/**
+ * Determines if a close code indicates a terminal error that should not
+ * trigger automatic reconnection.
+ *
+ * Close codes in the 4000-4999 range are application-defined terminal errors.
+ * The WebSocket client should NOT attempt to reconnect when receiving these codes.
+ *
+ * @param code - The WebSocket close code to check
+ * @returns `true` if the code indicates a terminal error, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * client.onClose((code, reason) => {
+ *   if (isTerminalCloseCode(code)) {
+ *     console.log('Terminal error, will not reconnect:', reason);
+ *   } else {
+ *     console.log('Transient error, will attempt reconnect');
+ *   }
+ * });
+ * ```
+ */
+export function isTerminalCloseCode(code: number): boolean {
+	if (code === CODER_WS_CLOSE_CODE.UNAVAILABLE || code === CODER_WS_CLOSE_CODE.RATE_LIMITED) {
+		return false;
+	}
+	return code >= 4000 && code < 5000;
+}

package/src/services/coder/discover.ts

@@ -4,12 +4,12 @@ import { normalizeCoderUrl } from './util.ts';
 
 export const DiscoverCoderUrlDataSchema = z
 	.object({
-		url: z.string().describe('Discovered base URL for the organization coder hub API'),
+		url: z.string().describe('Discovered base URL for the organization Coder URL'),
 	})
 	.describe('Response payload for coder URL discovery');
 
 /**
- * Discovers the org-specific Coder Hub URL through Catalyst.
+ * Discovers the org-specific Coder URL.
  *
  * Calls `GET /coder` on the Catalyst API. The org is resolved server-side
  * from the API key's auth context (not via query parameters).

package/src/services/coder/index.ts

@@ -20,6 +20,7 @@ export {
 	coderGetSession,
 	coderListConnectableSessions,
 	coderListSessions,
+	coderResumeSession,
 	coderUpdateSession,
 	CoderCreateSessionParamsSchema,
 	CoderGetSessionParamsSchema,
@@ -30,6 +31,7 @@ export {
 } from './sessions.ts';
 
 export * from './skills.ts';
+export * from './agents.ts';
 export * from './workspaces.ts';
 export * from './github.ts';
 
@@ -53,7 +55,7 @@ export { coderGetLoopState, CoderGetLoopStateParamsSchema } from './loop-state.t
 export type { CoderListUsersParamsWithOrg } from './users.ts';
 export { coderListUsers, CoderListUsersParamsWithOrgSchema } from './users.ts';
 
-export type { CoderClientOptions } from './client.ts';
+export type { CoderClientOptions, CoderRemoteAttachPreparationOptions } from './client.ts';
 export { CoderClient, CoderClientOptionsSchema } from './client.ts';
 
 export type { CoderErrorCode, CoderErrorContext } from './util.ts';
@@ -70,3 +72,29 @@ export {
 } from './util.ts';
 
 export { default as CoderAPIReference } from './api-reference.ts';
+
+export * from './protocol.ts';
+
+export { CODER_WS_CLOSE_CODE, type CoderWsCloseCode, isTerminalCloseCode } from './close-codes.ts';
+
+export type { CoderHubWebSocketState, CoderHubWebSocketOptions } from './websocket.ts';
+export {
+	CoderHubWebSocketClient,
+	CoderHubWebSocketOptionsSchema,
+	CoderHubWebSocketError,
+	subscribeToCoderHub,
+} from './websocket.ts';
+
+export type {
+	CoderSSEOptions,
+	CoderSSEEvent,
+	CoderSSEClientOptions,
+	CoderSSEState,
+} from './sse.ts';
+export {
+	CoderSSEOptionsSchema,
+	CoderSSEClientOptionsSchema,
+	CoderSSEError,
+	CoderSSEClient,
+	streamCoderSessionSSE,
+} from './sse.ts';