@agentuity/core 2.0.0-beta.1 → 2.0.0

package/src/services/oauth/token-storage.ts

@@ -0,0 +1,220 @@
+import type { KeyValueStorage } from '../keyvalue/service.ts';
+import type { OAuthFlowConfig, OAuthTokenResponse, StoredToken } from './types.ts';
+import { StoredTokenSchema } from './types.ts';
+import { refreshToken, logout } from './flow.ts';
+
+const DEFAULT_NAMESPACE = 'oauth-tokens';
+
+/**
+ * Check whether a stored token's access token has expired.
+ *
+ * @param token - The stored token to check
+ * @returns true if the token has an expires_at timestamp that is in the past
+ *
+ * @example
+ * ```typescript
+ * const token = await storage.get('user:123');
+ * if (token && isTokenExpired(token)) {
+ *   // Token is expired and auto-refresh wasn't available
+ * }
+ * ```
+ */
+export function isTokenExpired(token: StoredToken): boolean {
+	if (!token.expires_at) return false;
+	return Math.floor(Date.now() / 1000) >= token.expires_at;
+}
+
+/**
+ * Options for configuring a TokenStorage instance.
+ */
+export interface TokenStorageOptions {
+	/**
+	 * OAuth configuration for auto-refresh and token revocation.
+	 * If not provided, auto-refresh on get() and server-side revocation on invalidate() are disabled.
+	 */
+	config?: OAuthFlowConfig;
+
+	/**
+	 * KV namespace for storing tokens. Defaults to 'oauth-tokens'.
+	 */
+	namespace?: string;
+
+	/**
+	 * Key prefix prepended to all storage keys.
+	 * Useful for scoping tokens by application or tenant.
+	 */
+	prefix?: string;
+}
+
+/**
+ * Interface for storing, retrieving, and invalidating OAuth tokens.
+ *
+ * Implementations handle persistence and may support automatic token refresh
+ * on retrieval and server-side revocation on invalidation.
+ */
+export interface TokenStorage {
+	/**
+	 * Retrieve a stored token by key.
+	 *
+	 * If the token is expired and a refresh_token is available (and config is provided),
+	 * the token is automatically refreshed, stored, and the new token is returned.
+	 * If auto-refresh fails, the expired token is returned so the caller can decide
+	 * how to handle it (check with {@link isTokenExpired}).
+	 *
+	 * @param key - The storage key (e.g. a user ID or session ID)
+	 * @returns The stored token, or null if no token exists for the key
+	 */
+	get(key: string): Promise<StoredToken | null>;
+
+	/**
+	 * Store a token response from a token exchange or refresh.
+	 *
+	 * Automatically computes `expires_at` from `expires_in` if present.
+	 *
+	 * @param key - The storage key (e.g. a user ID or session ID)
+	 * @param token - The OAuth token response to store
+	 */
+	set(key: string, token: OAuthTokenResponse): Promise<void>;
+
+	/**
+	 * Invalidate a stored token: revoke it server-side and remove from storage.
+	 *
+	 * If config is provided, the refresh token (or access token as fallback)
+	 * is revoked via the token revocation endpoint. Revocation is best-effort —
+	 * the token is removed from storage regardless of whether revocation succeeds.
+	 *
+	 * @param key - The storage key to invalidate
+	 * @returns The token that was removed, or null if no token existed
+	 */
+	invalidate(key: string): Promise<StoredToken | null>;
+}
+
+/**
+ * Convert an OAuth token response to a StoredToken with computed expires_at.
+ */
+function toStoredToken(token: OAuthTokenResponse): StoredToken {
+	return {
+		access_token: token.access_token,
+		token_type: token.token_type,
+		refresh_token: token.refresh_token,
+		scope: token.scope,
+		id_token: token.id_token,
+		expires_at: token.expires_in ? Math.floor(Date.now() / 1000) + token.expires_in : undefined,
+	};
+}
+
+/**
+ * Token storage backed by Agentuity's Key-Value storage service.
+ *
+ * Stores tokens as JSON in a KV namespace. Supports automatic token refresh
+ * on retrieval when tokens expire (if OAuth config is provided).
+ *
+ * @example
+ * ```typescript
+ * import { KeyValueTokenStorage } from '@agentuity/core/oauth';
+ *
+ * // Create storage with auto-refresh enabled
+ * const storage = new KeyValueTokenStorage(ctx.kv, {
+ *   config: { issuer: 'https://auth.example.com' },
+ * });
+ *
+ * // Store a token after initial exchange
+ * await storage.set('user:123', tokenResponse);
+ *
+ * // Retrieve — auto-refreshes if expired
+ * const token = await storage.get('user:123');
+ *
+ * // Logout — revokes server-side and removes from storage
+ * await storage.invalidate('user:123');
+ * ```
+ */
+export class KeyValueTokenStorage implements TokenStorage {
+	#kv: KeyValueStorage;
+	#namespace: string;
+	#prefix: string;
+	#config?: OAuthFlowConfig;
+
+	constructor(kv: KeyValueStorage, options?: TokenStorageOptions) {
+		this.#kv = kv;
+		this.#namespace = options?.namespace ?? DEFAULT_NAMESPACE;
+		this.#prefix = options?.prefix ?? '';
+		this.#config = options?.config;
+	}
+
+	async get(key: string): Promise<StoredToken | null> {
+		const result = await this.#kv.get<StoredToken>(this.#namespace, this.#resolveKey(key));
+		if (!result.exists) return null;
+
+		const parsed = StoredTokenSchema.safeParse(result.data);
+		if (!parsed.success) return null;
+
+		const token = parsed.data;
+
+		// Auto-refresh if expired and refresh_token + config are available
+		if (isTokenExpired(token) && token.refresh_token && this.#config) {
+			try {
+				const newTokenResponse = await refreshToken(token.refresh_token, this.#config);
+				const newStored = toStoredToken(newTokenResponse);
+				await this.#store(key, newStored);
+				return newStored;
+			} catch {
+				// Refresh failed — return the expired token, caller can check isTokenExpired()
+				return token;
+			}
+		}
+
+		return token;
+	}
+
+	async set(key: string, token: OAuthTokenResponse): Promise<void> {
+		const stored = toStoredToken(token);
+		await this.#store(key, stored);
+	}
+
+	async invalidate(key: string): Promise<StoredToken | null> {
+		const resolvedKey = this.#resolveKey(key);
+		const result = await this.#kv.get<StoredToken>(this.#namespace, resolvedKey);
+
+		if (!result.exists) return null;
+
+		const parsed = StoredTokenSchema.safeParse(result.data);
+		const token = parsed.success ? parsed.data : null;
+
+		// Revoke server-side (best effort)
+		if (token && this.#config) {
+			const tokenToRevoke = token.refresh_token ?? token.access_token;
+			try {
+				await logout(tokenToRevoke, this.#config);
+			} catch {
+				// Best effort — continue with storage cleanup
+			}
+		}
+
+		// Remove from storage regardless of revocation result
+		await this.#kv.delete(this.#namespace, resolvedKey);
+
+		return token;
+	}
+
+	async #store(key: string, token: StoredToken): Promise<void> {
+		// Only set explicit TTL for tokens without a refresh_token.
+		// Tokens with refresh capability persist until explicitly invalidated
+		// (auto-refresh on get() will keep them fresh).
+		let ttl: number | undefined;
+		if (!token.refresh_token && token.expires_at) {
+			const remaining = token.expires_at - Math.floor(Date.now() / 1000);
+			if (remaining > 0) {
+				ttl = Math.max(remaining, 60); // KV minimum is 60 seconds
+			}
+		}
+
+		await this.#kv.set(this.#namespace, this.#resolveKey(key), token, {
+			ttl,
+			contentType: 'application/json',
+		});
+	}
+
+	#resolveKey(key: string): string {
+		return this.#prefix ? `${this.#prefix}${key}` : key;
+	}
+}

package/src/services/oauth/types.ts

@@ -155,6 +155,8 @@ export const OAuthPermissionLevelSchema = z.object({
 	label: z.string(),
 	value: z.string(),
 	scopes: z.array(z.string()),
+	warning: z.boolean().optional(),
+	warningTitle: z.string().optional(),
 });
 
 export type OAuthPermissionLevel = z.infer<typeof OAuthPermissionLevelSchema>;
@@ -268,6 +270,18 @@ export const OAuthFlowConfigSchema = z.object({
 		.string()
 		.optional()
 		.describe('UserInfo endpoint. Defaults to OAUTH_USERINFO_URL or {issuer}/userinfo'),
+	revokeUrl: z
+		.string()
+		.optional()
+		.describe(
+			'Token revocation endpoint (RFC 7009). Defaults to OAUTH_REVOKE_URL or {issuer}/revoke'
+		),
+	endSessionUrl: z
+		.string()
+		.optional()
+		.describe(
+			'OIDC end session endpoint. Defaults to OAUTH_END_SESSION_URL or {issuer}/end_session'
+		),
 	scopes: z
 		.string()
 		.optional()
@@ -305,3 +319,17 @@ export const OAuthUserInfoSchema = z
 	.catchall(z.unknown());
 
 export type OAuthUserInfo = z.infer<typeof OAuthUserInfoSchema>;
+
+export const StoredTokenSchema = z.object({
+	access_token: z.string(),
+	token_type: z.string().optional(),
+	refresh_token: z.string().optional(),
+	scope: z.string().optional(),
+	id_token: z.string().optional(),
+	expires_at: z
+		.number()
+		.optional()
+		.describe('Unix timestamp (seconds) when the access token expires'),
+});
+
+export type StoredToken = z.infer<typeof StoredTokenSchema>;

package/src/services/project/get.ts

@@ -16,9 +16,18 @@ export const ProjectSchema = z.object({
 	orgId: z.string().describe('the organization id'),
 	cloudRegion: z.string().nullable().optional().describe('the cloud region'),
 	vanityHostname: z.string().nullable().optional().describe('the vanity hostname'),
+	domains: z.array(z.string()).nullable().optional().describe('custom domains for the project'),
 	api_key: z.string().optional().describe('the SDK api key for the project'),
 	env: z.record(z.string(), z.string()).optional().describe('the environment key/values'),
 	secrets: z.record(z.string(), z.string()).optional().describe('the secrets key/values'),
+	urls: z
+		.object({
+			dashboard: z.string().describe('the dashboard URL for the project'),
+			app: z.string().describe('the public URL for the latest deployment'),
+			custom: z.array(z.string()).describe('custom domain URLs'),
+		})
+		.optional()
+		.describe('project URLs'),
 });
 
 export const ProjectGetResponseSchema = APIResponseSchema(ProjectSchema);

package/src/services/sandbox/create.ts

@@ -102,6 +102,12 @@ export const SandboxCreateRequestSchema = z
 			.record(z.string(), z.unknown())
 			.optional()
 			.describe('Optional user-defined metadata to associate with the sandbox'),
+		scopes: z
+			.array(z.string())
+			.optional()
+			.describe(
+				'Permission scopes for automatic service access (e.g., "services:read", "services:write").'
+			),
 	})
 	.refine(
 		(data) => {
@@ -230,6 +236,9 @@ export async function sandboxCreate(
 	if (options.metadata) {
 		body.metadata = options.metadata;
 	}
+	if (options.scopes && options.scopes.length > 0) {
+		body.scopes = options.scopes;
+	}
 
 	const queryParams = new URLSearchParams();
 	if (orgId) {

package/src/services/sandbox/execute.ts

@@ -1,7 +1,7 @@
 import type { ExecuteOptions, Execution, ExecutionStatus } from './types.ts';
 import { z } from 'zod';
 import type { APIClient } from '../api.ts';
-import { SandboxBusyError, throwSandboxError } from './util.ts';
+import { SandboxBusyError, SandboxNotFoundError, throwSandboxError } from './util.ts';
 
 export const ExecuteRequestSchema = z
 	.object({
@@ -114,23 +114,37 @@ export async function sandboxExecute(
 			signal ?? options.signal
 		);
 	} catch (error: unknown) {
-		// Detect 409 Conflict (sandbox busy) and throw a specific error.
-		// The sandbox API client is configured with maxRetries: 0 to fail fast
-		// when sandbox is busy (retrying wouldn't help - sandbox is still busy).
-		// Convert APIErrorResponse with status 409 to SandboxBusyError for clarity.
 		if (
 			error &&
 			typeof error === 'object' &&
 			'_tag' in error &&
 			(error as { _tag: string })._tag === 'APIErrorResponse' &&
-			'status' in error &&
-			(error as { status: number }).status === 409
+			'status' in error
 		) {
-			throw new SandboxBusyError({
-				message:
-					'Sandbox is currently busy executing another command. Please wait for the current execution to complete before submitting a new one.',
-				sandboxId,
-			});
+			const status = (error as { status: number }).status;
+
+			// Detect 404 Not Found — sandbox may not exist or may still be initializing.
+			// The server normally handles the creating→idle wait transparently, but this
+			// provides a clear typed error if a 404 reaches the SDK for any reason.
+			if (status === 404) {
+				throw new SandboxNotFoundError({
+					message:
+						'Sandbox not found. If you just created this sandbox, it may still be initializing. The server should handle this automatically — if this persists, the sandbox may have been destroyed.',
+					sandboxId,
+				});
+			}
+
+			// Detect 409 Conflict (sandbox busy) and throw a specific error.
+			// The sandbox API client is configured with maxRetries: 0 to fail fast
+			// when sandbox is busy (retrying wouldn't help - sandbox is still busy).
+			// Convert APIErrorResponse with status 409 to SandboxBusyError for clarity.
+			if (status === 409) {
+				throw new SandboxBusyError({
+					message:
+						'Sandbox is currently busy executing another command. Please wait for the current execution to complete before submitting a new one.',
+					sandboxId,
+				});
+			}
 		}
 		throw error;
 	}

package/src/services/sandbox/run.ts

@@ -224,20 +224,103 @@ export async function sandboxRun(
 		logger?.debug('streams completed, fetching final status');
 
 		// Stream EOF means the sandbox is done — hadron only closes streams after the
-		// container exits. Fetch status once for the exit code; if lifecycle events
-		// haven't propagated to Catalyst yet, default to exit code 0.
+		// container exits. Poll for the exit code with retries because the lifecycle
+		// event (carrying the exit code) may still be in flight to Catalyst when the
+		// stream completes.
+		//
+		// Hadron drains container logs for up to 5s after exit, then closes the
+		// stream, then sends the lifecycle event in a goroutine. So the exit code
+		// typically arrives at Catalyst 5–7s after the container exits. We use a
+		// linear 1s polling interval (not exponential backoff) so we don't overshoot
+		// the window — 15 attempts × 1s = 15s total, which comfortably covers the
+		// drain + lifecycle propagation delay.
+		// Abort-aware sleep that rejects when the caller's signal fires.
+		const abortAwareSleep = (ms: number): Promise<void> =>
+			new Promise((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(new DOMException('Aborted', 'AbortError'));
+					return;
+				}
+				const timer = setTimeout(resolve, ms);
+				signal?.addEventListener(
+					'abort',
+					() => {
+						clearTimeout(timer);
+						reject(new DOMException('Aborted', 'AbortError'));
+					},
+					{ once: true }
+				);
+			});
+
 		let exitCode = 0;
-		try {
-			const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
-			if (sandboxStatus.exitCode != null) {
-				exitCode = sandboxStatus.exitCode;
-			} else if (sandboxStatus.status === 'failed') {
-				exitCode = 1;
+		const maxStatusRetries = 15;
+		const statusPollInterval = 1000;
+		const statusPollStart = Date.now();
+		for (let attempt = 0; attempt < maxStatusRetries; attempt++) {
+			if (signal?.aborted) {
+				break;
+			}
+			try {
+				const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
+				if (sandboxStatus.exitCode != null) {
+					exitCode = sandboxStatus.exitCode;
+					logger?.debug(
+						'[run] exit code %d found on attempt %d/%d (+%dms)',
+						exitCode,
+						attempt + 1,
+						maxStatusRetries,
+						Date.now() - statusPollStart
+					);
+					break;
+				} else if (sandboxStatus.status === 'failed') {
+					exitCode = 1;
+					logger?.debug(
+						'[run] sandbox failed on attempt %d/%d (+%dms)',
+						attempt + 1,
+						maxStatusRetries,
+						Date.now() - statusPollStart
+					);
+					break;
+				} else if (sandboxStatus.status === 'terminated') {
+					// Sandbox was destroyed. If exit code is missing, the
+					// terminated event may have overwritten it. Stop polling —
+					// no further updates will come.
+					logger?.debug(
+						'[run] sandbox terminated without exit code on attempt %d/%d (+%dms)',
+						attempt + 1,
+						maxStatusRetries,
+						Date.now() - statusPollStart
+					);
+					break;
+				}
+				// Exit code not yet propagated — wait before next poll.
+				if (attempt < maxStatusRetries - 1) {
+					await abortAwareSleep(statusPollInterval);
+				}
+			} catch (err) {
+				if (err instanceof DOMException && err.name === 'AbortError') {
+					break;
+				}
+				// Transient failure (sandbox briefly unavailable, network error).
+				// Retry instead of giving up — the lifecycle event may still arrive.
+				logger?.debug(
+					'[run] sandboxGetStatus attempt %d/%d failed (+%dms): %s',
+					attempt + 1,
+					maxStatusRetries,
+					Date.now() - statusPollStart,
+					err
+				);
+				if (attempt < maxStatusRetries - 1) {
+					await abortAwareSleep(statusPollInterval);
+				}
 			}
-		} catch {
-			// Sandbox may already be destroyed (fire-and-forget teardown).
-			// Stream EOF already confirmed execution completed.
-			logger?.debug('sandboxGetStatus failed after stream EOF, using default exit code 0');
+		}
+		if (exitCode === 0) {
+			logger?.debug(
+				'[run] exit code polling finished with default 0 after %d attempts (+%dms)',
+				maxStatusRetries,
+				Date.now() - statusPollStart
+			);
 		}
 
 		if (timingLogsEnabled)
@@ -387,44 +470,56 @@ async function streamUrlToWritable(
 	writable: Writable,
 	signal: AbortSignal,
 	logger?: Logger,
-	started?: number
+	_started?: number
 ): Promise<void> {
+	const streamStart = Date.now();
 	try {
-		logger?.debug('fetching stream: %s', url);
-		const response = await fetch(url, { signal });
-		logger?.debug('stream response status: %d', response.status);
-		if (timingLogsEnabled && started)
-			console.error(
-				`[TIMING] +${Date.now() - started}ms: stream response received (status: ${response.status})`
-			);
+		// Signal to Pulse that this is a v2 stream so it waits for v2 metadata
+		// instead of falling back to the legacy download path on a short timeout.
+		const v2Url = new URL(url);
+		v2Url.searchParams.set('v', '2');
+		logger?.debug('[stream] fetching: %s', v2Url.href);
+		const response = await fetch(v2Url.href, { signal });
+		logger?.debug(
+			'[stream] response status=%d in %dms',
+			response.status,
+			Date.now() - streamStart
+		);
 
 		if (!response.ok || !response.body) {
-			logger?.debug('stream response not ok or no body');
+			logger?.debug('[stream] not ok or no body (status=%d) — returning empty', response.status);
 			return;
 		}
 
 		const reader = response.body.getReader();
-		let firstChunk = true;
+		let chunks = 0;
+		let totalBytes = 0;
 
 		// Read until EOF - Pulse will block until data is available
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) {
-				logger?.debug('stream EOF');
-				if (timingLogsEnabled && started)
-					console.error(`[TIMING] +${Date.now() - started}ms: stream EOF`);
+				logger?.debug(
+					'[stream] EOF after %dms (%d chunks, %d bytes)',
+					Date.now() - streamStart,
+					chunks,
+					totalBytes
+				);
 				break;
 			}
 
 			if (value) {
-				if (firstChunk && started) {
-					if (timingLogsEnabled)
-						console.error(
-							`[TIMING] +${Date.now() - started}ms: first chunk (${value.length} bytes)`
-						);
-					firstChunk = false;
+				chunks++;
+				totalBytes += value.length;
+				if (chunks <= 3 || chunks % 100 === 0) {
+					logger?.debug(
+						'[stream] chunk #%d: %d bytes (total: %d bytes, +%dms)',
+						chunks,
+						value.length,
+						totalBytes,
+						Date.now() - streamStart
+					);
 				}
-				logger?.debug('stream chunk: %d bytes', value.length);
 				await writeAndDrain(writable, value);
 			}
 		}
@@ -433,9 +528,9 @@ async function streamUrlToWritable(
 		writable.end();
 	} catch (err) {
 		if (err instanceof Error && err.name === 'AbortError') {
-			logger?.debug('stream aborted');
+			logger?.debug('[stream] aborted after %dms', Date.now() - streamStart);
 			return;
 		}
-		logger?.debug('stream error: %s', err);
+		logger?.debug('[stream] error after %dms: %s', Date.now() - streamStart, err);
 	}
 }

package/src/services/sandbox/types.ts

@@ -328,6 +328,13 @@ export const SandboxCreateOptionsSchema = z.object({
 		.record(z.string(), z.unknown())
 		.optional()
 		.describe('Optional user-defined metadata to associate with the sandbox.'),
+	/** Permission scopes for automatic service access (e.g., "services:read", "services:write"). */
+	scopes: z
+		.array(z.string())
+		.optional()
+		.describe(
+			'Permission scopes for automatic service access (e.g., "services:read", "services:write").'
+		),
 });
 export type SandboxCreateOptions = z.infer<typeof SandboxCreateOptionsSchema>;
 
@@ -398,6 +405,20 @@ export const SandboxSchema = z.object({
 		.describe('Resume the sandbox from a paused or evacuated state.'),
 	/** Destroy the sandbox */
 	destroy: z.custom<() => Promise<void>>().describe('Destroy the sandbox'),
+	/** Create a new job in the sandbox */
+	createJob: z
+		.custom<(options: CreateJobOptions) => Promise<Job>>()
+		.describe('Create a new job in the sandbox'),
+	/** Get a job by ID */
+	getJob: z.custom<(jobId: string) => Promise<Job>>().describe('Get a job by ID'),
+	/** List jobs in the sandbox */
+	listJobs: z
+		.custom<(limit?: number) => Promise<{ jobs: Job[] }>>()
+		.describe('List jobs in the sandbox'),
+	/** Stop a running job */
+	stopJob: z
+		.custom<(jobId: string, force?: boolean) => Promise<Job>>()
+		.describe('Stop a running job'),
 });
 export type Sandbox = z.infer<typeof SandboxSchema>;
 

package/src/services/schedule/service.ts

@@ -58,6 +58,18 @@ export const ScheduleSchema = z.object({
 	 * the schedule fires or the expression is changed.
 	 */
 	due_date: z.string().describe('ISO 8601 timestamp of the next scheduled execution.'),
+
+	/**
+	 * Whether this is a system-managed schedule.
+	 *
+	 * @remarks Internal schedules are created by the system and cannot be modified
+	 * or deleted by users.
+	 */
+	internal: z
+		.boolean()
+		.describe(
+			'Whether this is a system-managed schedule. Internal schedules cannot be modified or deleted users.'
+		),
 });
 
 export type Schedule = z.infer<typeof ScheduleSchema>;
@@ -204,6 +216,14 @@ export const CreateScheduleParamsSchema = z.object({
 	 */
 	expression: z.string().describe('Cron expression defining when the schedule fires'),
 
+	/**
+	 * Whether this is a system-managed schedule.
+	 *
+	 * @remarks Internal schedules are created by the system for workflows and cannot
+	 * be modified or deleted directly by users.
+	 */
+	internal: z.boolean().optional().describe('Whether this is a system-managed schedule.'),
+
 	/**
 	 * Optional array of destinations to create alongside the schedule.
 	 *