@agentuity/core 1.0.59 → 2.0.0-beta.1

package/src/deprecation.ts

@@ -0,0 +1,120 @@
+/**
+ * Deprecation warning for v1 SDK packages.
+ *
+ * This module logs a deprecation warning when v1 packages are used,
+ * recommending migration to v2.
+ *
+ * The warning is only shown once per process to avoid noise.
+ */
+
+import type { Logger } from './logger';
+
+let deprecationWarningShown = false;
+
+/**
+ * Package version info
+ */
+interface PackageVersion {
+	version: string;
+	major: number;
+}
+
+/**
+ * Get version from package.json using various strategies.
+ */
+function getPackageVersion(): PackageVersion | null {
+	try {
+		// Try to read from the bundled package.json
+		// When bundled by Bun/Vite, import.meta.resolve can find the package.json
+		const pkgUrl = import.meta.resolve('@agentuity/core/package.json');
+		const pkg = require(pkgUrl);
+		if (pkg?.version) {
+			const match = pkg.version.match(/^(\d+)\.\d+\.\d+/);
+			return {
+				version: pkg.version,
+				major: match ? parseInt(match[1], 10) : 0,
+			};
+		}
+	} catch {
+		// Try require fallback
+		try {
+			const pkg = require('@agentuity/core/package.json');
+			if (pkg?.version) {
+				const match = pkg.version.match(/^(\d+)\.\d+\.\d+/);
+				return {
+					version: pkg.version,
+					major: match ? parseInt(match[1], 10) : 0,
+				};
+			}
+		} catch {
+			// Ignore
+		}
+	}
+	return null;
+}
+
+/**
+ * Show deprecation warning for v1 packages.
+ *
+ * @param logger - Optional logger instance (falls back to console)
+ */
+export function showDeprecationWarning(logger?: Logger): void {
+	// Only show once per process
+	if (deprecationWarningShown) {
+		return;
+	}
+
+	// Skip if explicitly disabled
+	if (process.env.AGENTUITY_NO_DEPRECATION_WARNING === 'true') {
+		return;
+	}
+
+	// Skip in test environments
+	if (process.env.NODE_ENV === 'test' || process.env.VITEST === 'true') {
+		return;
+	}
+
+	const pkgVersion = getPackageVersion();
+
+	// Only warn if this is a v1 package
+	if (!pkgVersion || pkgVersion.major !== 1) {
+		return;
+	}
+
+	deprecationWarningShown = true;
+
+	const message =
+		'\n' +
+		'┌──────────────────────────────────────────────────────────────────────┐\n' +
+		'│                                                                      │\n' +
+		'│  ⚠️  Agentuity SDK v1 is deprecated                                  │\n' +
+		'│                                                                      │\n' +
+		'│  You are using @agentuity/core@' +
+		pkgVersion.version.padEnd(22) +
+		'         │\n' +
+		'│                                                                      │\n' +
+		'│  v2 introduces major improvements:                                   │\n' +
+		'│    • Hono RPC for end-to-end type safety                            │\n' +
+		'│    • Vite-native dev server with HMR                                 │\n' +
+		'│    • Simplified configuration in createApp()                         │\n' +
+		'│                                                                      │\n' +
+		'│  → Run `npx @agentuity/migrate` to upgrade your project             │\n' +
+		'│                                                                      │\n' +
+		'│  Docs: https://docs.agentuity.com/migration/v1-to-v2                │\n' +
+		'│                                                                      │\n' +
+		'└──────────────────────────────────────────────────────────────────────┘\n';
+
+	if (logger) {
+		logger.warn(message);
+	} else {
+		console.warn(message);
+	}
+}
+
+/**
+ * Check if the current package is v1.
+ */
+export function isV1Package(): boolean {
+	const pkgVersion = getPackageVersion();
+	return pkgVersion?.major === 1;
+}

package/src/index.ts

@@ -2,6 +2,9 @@
 export type { EnvField, ResourceType } from './env-example.ts';
 export { detectResourceFromKey, parseEnvExample } from './env-example.ts';
 
+// deprecation.ts exports
+export { isV1Package, showDeprecationWarning } from './deprecation';
+
 // error.ts exports
 export { isStructuredError, RichError, StructuredError } from './error.ts';
 

package/src/services/oauth/flow.ts

@@ -25,28 +25,11 @@ function resolveConfig(config?: OAuthFlowConfig) {
 		config?.userinfoUrl ??
 		getEnv('OAUTH_USERINFO_URL') ??
 		(issuer ? `${issuer}/userinfo` : undefined);
-	const revokeUrl =
-		config?.revokeUrl ?? getEnv('OAUTH_REVOKE_URL') ?? (issuer ? `${issuer}/revoke` : undefined);
-	const endSessionUrl =
-		config?.endSessionUrl ??
-		getEnv('OAUTH_END_SESSION_URL') ??
-		(issuer ? `${issuer}/end_session` : undefined);
 	const scopes = config?.scopes ?? getEnv('OAUTH_SCOPES') ?? 'openid profile email';
 
 	const prompt = config?.prompt;
 
-	return {
-		clientId,
-		clientSecret,
-		issuer,
-		authorizeUrl,
-		tokenUrl,
-		userinfoUrl,
-		revokeUrl,
-		endSessionUrl,
-		scopes,
-		prompt,
-	};
+	return { clientId, clientSecret, issuer, authorizeUrl, tokenUrl, userinfoUrl, scopes, prompt };
 }
 
 /**
@@ -135,6 +118,9 @@ export async function exchangeToken(
 		});
 	}
 
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
 	let response: Response;
 	try {
 		response = await fetch(resolved.tokenUrl, {
@@ -147,16 +133,18 @@ export async function exchangeToken(
 				client_id: resolved.clientId,
 				client_secret: resolved.clientSecret,
 			}),
-			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+			signal: controller.signal,
 		});
 	} catch (err) {
-		if (err instanceof DOMException && err.name === 'TimeoutError') {
+		clearTimeout(timer);
+		if (err instanceof DOMException && err.name === 'AbortError') {
 			throw new OAuthResponseError({
 				message: `Token exchange timed out after ${DEFAULT_TIMEOUT_MS}ms`,
 			});
 		}
 		throw err;
 	}
+	clearTimeout(timer);
 
 	if (!response.ok) {
 		const error = await response.text();
@@ -169,140 +157,6 @@ export async function exchangeToken(
 	return OAuthTokenResponseSchema.parse(data);
 }
 
-/**
- * Refresh an access token using a refresh token.
- *
- * @param refreshTokenValue - The refresh token obtained from a previous token exchange
- * @param config - Optional OAuth configuration. Falls back to environment variables.
- * @returns The token response including a new access_token, and optionally a new refresh_token
- *
- * @example
- * ```typescript
- * const newToken = await refreshToken(previousToken.refresh_token!);
- * console.log(newToken.access_token);
- * ```
- */
-export async function refreshToken(
-	refreshTokenValue: string,
-	config?: OAuthFlowConfig
-): Promise<OAuthTokenResponse> {
-	const resolved = resolveConfig(config);
-
-	if (!resolved.tokenUrl) {
-		throw new OAuthResponseError({
-			message:
-				'No token URL configured. Set OAUTH_TOKEN_URL or OAUTH_ISSUER environment variable.',
-		});
-	}
-	if (!resolved.clientId) {
-		throw new OAuthResponseError({
-			message: 'No client ID configured. Set OAUTH_CLIENT_ID environment variable.',
-		});
-	}
-
-	const params = new URLSearchParams({
-		grant_type: 'refresh_token',
-		refresh_token: refreshTokenValue,
-		client_id: resolved.clientId,
-	});
-
-	if (resolved.clientSecret) {
-		params.set('client_secret', resolved.clientSecret);
-	}
-
-	let response: Response;
-	try {
-		response = await fetch(resolved.tokenUrl, {
-			method: 'POST',
-			headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-			body: params,
-			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
-		});
-	} catch (err) {
-		if (err instanceof DOMException && err.name === 'TimeoutError') {
-			throw new OAuthResponseError({
-				message: `Token refresh timed out after ${DEFAULT_TIMEOUT_MS}ms`,
-			});
-		}
-		throw err;
-	}
-
-	if (!response.ok) {
-		const error = await response.text();
-		throw new OAuthResponseError({
-			message: `Token refresh failed (${response.status}): ${error}`,
-		});
-	}
-
-	const data = await response.json();
-	return OAuthTokenResponseSchema.parse(data);
-}
-
-/**
- * Revoke an OAuth token (access token or refresh token) to log the user out.
- *
- * Calls the token revocation endpoint (RFC 7009). The server will invalidate
- * the token so it can no longer be used. Per the spec, the endpoint returns
- * a success response even if the token was already invalid.
- *
- * @param token - The access token or refresh token to revoke
- * @param config - Optional OAuth configuration. Falls back to environment variables.
- *
- * @example
- * ```typescript
- * // Revoke the refresh token to fully log out
- * await logout(token.refresh_token!);
- * ```
- */
-export async function logout(token: string, config?: OAuthFlowConfig): Promise<void> {
-	const resolved = resolveConfig(config);
-
-	if (!resolved.revokeUrl) {
-		throw new OAuthResponseError({
-			message:
-				'No revoke URL configured. Set OAUTH_REVOKE_URL or OAUTH_ISSUER environment variable.',
-		});
-	}
-	if (!resolved.clientId) {
-		throw new OAuthResponseError({
-			message: 'No client ID configured. Set OAUTH_CLIENT_ID environment variable.',
-		});
-	}
-
-	const params = new URLSearchParams({
-		token,
-		client_id: resolved.clientId,
-	});
-
-	if (resolved.clientSecret) {
-		params.set('client_secret', resolved.clientSecret);
-	}
-
-	let response: Response;
-	try {
-		response = await fetch(resolved.revokeUrl, {
-			method: 'POST',
-			headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-			body: params,
-			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
-		});
-	} catch (err) {
-		if (err instanceof DOMException && err.name === 'TimeoutError') {
-			throw new OAuthResponseError({
-				message: `Token revocation timed out after ${DEFAULT_TIMEOUT_MS}ms`,
-			});
-		}
-		throw err;
-	}
-
-	if (!response.ok) {
-		const error = await response.text();
-		throw new OAuthResponseError({
-			message: `Token revocation failed (${response.status}): ${error}`,
-		});
-	}
-}
-
 /**
  * Fetch user information from the OIDC userinfo endpoint using an access token.
  *
@@ -329,20 +183,25 @@ export async function fetchUserInfo(
 		});
 	}
 
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
 	let response: Response;
 	try {
 		response = await fetch(resolved.userinfoUrl, {
 			headers: { Authorization: `Bearer ${accessToken}` },
-			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+			signal: controller.signal,
 		});
 	} catch (err) {
-		if (err instanceof DOMException && err.name === 'TimeoutError') {
+		clearTimeout(timer);
+		if (err instanceof DOMException && err.name === 'AbortError') {
 			throw new OAuthResponseError({
 				message: `Userinfo request timed out after ${DEFAULT_TIMEOUT_MS}ms`,
 			});
 		}
 		throw err;
 	}
+	clearTimeout(timer);
 
 	if (!response.ok) {
 		const error = await response.text();

package/src/services/oauth/index.ts

@@ -7,4 +7,3 @@ export * from './members.ts';
 export * from './keys.ts';
 export * from './util.ts';
 export * from './flow.ts';
-export * from './token-storage.ts';

package/src/services/oauth/types.ts

@@ -268,18 +268,6 @@ 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()
@@ -317,17 +305,3 @@ 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/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, SandboxNotFoundError, throwSandboxError } from './util.ts';
+import { SandboxBusyError, throwSandboxError } from './util.ts';
 
 export const ExecuteRequestSchema = z
 	.object({
@@ -114,37 +114,23 @@ 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
+			'status' in error &&
+			(error as { status: number }).status === 409
 		) {
-			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 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,103 +224,20 @@ 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. 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 }
-				);
-			});
-
+		// container exits. Fetch status once for the exit code; if lifecycle events
+		// haven't propagated to Catalyst yet, default to exit code 0.
 		let exitCode = 0;
-		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);
-				}
+		try {
+			const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
+			if (sandboxStatus.exitCode != null) {
+				exitCode = sandboxStatus.exitCode;
+			} else if (sandboxStatus.status === 'failed') {
+				exitCode = 1;
 			}
-		}
-		if (exitCode === 0) {
-			logger?.debug(
-				'[run] exit code polling finished with default 0 after %d attempts (+%dms)',
-				maxStatusRetries,
-				Date.now() - statusPollStart
-			);
+		} 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 (timingLogsEnabled)
@@ -470,56 +387,44 @@ async function streamUrlToWritable(
 	writable: Writable,
 	signal: AbortSignal,
 	logger?: Logger,
-	_started?: number
+	started?: number
 ): Promise<void> {
-	const streamStart = Date.now();
 	try {
-		// 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
-		);
+		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})`
+			);
 
 		if (!response.ok || !response.body) {
-			logger?.debug('[stream] not ok or no body (status=%d) — returning empty', response.status);
+			logger?.debug('stream response not ok or no body');
 			return;
 		}
 
 		const reader = response.body.getReader();
-		let chunks = 0;
-		let totalBytes = 0;
+		let firstChunk = true;
 
 		// Read until EOF - Pulse will block until data is available
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) {
-				logger?.debug(
-					'[stream] EOF after %dms (%d chunks, %d bytes)',
-					Date.now() - streamStart,
-					chunks,
-					totalBytes
-				);
+				logger?.debug('stream EOF');
+				if (timingLogsEnabled && started)
+					console.error(`[TIMING] +${Date.now() - started}ms: stream EOF`);
 				break;
 			}
 
 			if (value) {
-				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
-					);
+				if (firstChunk && started) {
+					if (timingLogsEnabled)
+						console.error(
+							`[TIMING] +${Date.now() - started}ms: first chunk (${value.length} bytes)`
+						);
+					firstChunk = false;
 				}
+				logger?.debug('stream chunk: %d bytes', value.length);
 				await writeAndDrain(writable, value);
 			}
 		}
@@ -528,9 +433,9 @@ async function streamUrlToWritable(
 		writable.end();
 	} catch (err) {
 		if (err instanceof Error && err.name === 'AbortError') {
-			logger?.debug('[stream] aborted after %dms', Date.now() - streamStart);
+			logger?.debug('stream aborted');
 			return;
 		}
-		logger?.debug('[stream] error after %dms: %s', Date.now() - streamStart, err);
+		logger?.debug('stream error: %s', err);
 	}
 }

package/src/services/sandbox/types.ts

@@ -398,20 +398,6 @@ 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>;