engineering-memory 1.7.0 → 1.9.0

package/runtime/dist/src/runtime/api-client.js

@@ -1,4 +1,47 @@
 import { sha256, stableStringify } from '../utilities/hash.js';
+export const backendRecoveryOperationNames = [
+    'auth.signin_browser',
+    'auth.web_csrf',
+    'auth.web_signin',
+    'audit.list',
+    'organization.member_list',
+    'organization.member_upsert',
+    'project.setup',
+    'project.resolve',
+    'project.list',
+    'project.restore',
+    'project.member_list',
+    'organization.list',
+    'project.member_add',
+    'work_item.list',
+    'work_item.get',
+    'session.bootstrap',
+    'session.resume',
+    'context.refresh',
+    'context.prepare_change',
+    'memory.query',
+    'memory.history',
+    'memory.propose_revision',
+    'memory.list_proposals',
+    'memory.review_proposal',
+    'architecture.plan',
+    'architecture.record_application',
+    'task.checkpoint',
+    'task.reconcile',
+    'task.self_review',
+    'task.verify',
+    'task.close',
+    'task.abandon',
+    'task.branch',
+    'task.resolve_pending_delivery',
+];
+const backendRecoveryOperations = new Set(backendRecoveryOperationNames);
+const browserSigninRecovery = 'auth.signin_browser';
+export function normalizeBackendRecovery(value) {
+    return typeof value === 'string' && backendRecoveryOperations.has(value)
+        ? value
+        : null;
+}
 export class BackendUnavailableError extends Error {
     causeValue;
     retryable = true;
@@ -14,14 +57,17 @@ export class ApiResponseError extends Error {
     retryable;
     envelope;
     recovery;
-    constructor(message, httpStatus, code, retryable, envelope, recovery = null) {
-        super(message);
+    constructor(message, httpStatus, code, retryable, envelope, recovery) {
+        const normalizedRecovery = normalizeBackendRecovery(recovery) ?? (httpStatus === 401 ? browserSigninRecovery : null);
+        super(normalizedRecovery && !message.includes('Recovery: call ')
+            ? `${message} Recovery: call ${normalizedRecovery}.`
+            : message);
         this.httpStatus = httpStatus;
         this.code = code;
         this.retryable = retryable;
         this.envelope = envelope;
-        this.recovery = recovery;
         this.name = 'ApiResponseError';
+        this.recovery = normalizedRecovery;
     }
 }
 export class ApiClient {
@@ -53,7 +99,7 @@ export class ApiClient {
         if (request.authenticated !== false) {
             const accessToken = await this.options.credentials.get('access-token');
             if (!accessToken) {
-                throw new ApiResponseError('Authentication is required', 401, null, false, null);
+                throw new ApiResponseError('Authentication is required. Recovery: call auth.signin_browser.', 401, null, false, null, browserSigninRecovery);
             }
             headers.Authorization = `Bearer ${accessToken}`;
         }
@@ -108,9 +154,9 @@ export class ApiClient {
                 this.responseSources.set(cached.value, 'stale_cache');
                 return cached.value;
             }
-            const recovery = envelope.errorModel?.recovery ?? null;
+            const recovery = envelope.errorModel?.recovery ?? (response.status === 401 ? browserSigninRecovery : null);
             const refusal = envelope.errorModel?.text ?? envelope.message ?? `Backend returned ${response.status}`;
-            throw new ApiResponseError(recovery ? `${refusal} Recovery: call ${recovery}.` : refusal, response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope, recovery);
+            throw new ApiResponseError(refusal, response.status, envelope.errorModel?.code ?? null, retryableResponse(response.status, envelope.errorModel?.retryable), envelope, recovery);
         }
         if (request.cacheKey) {
             await this.options.cache.set(cacheKey, response.headers.get('etag'), envelope);
@@ -146,7 +192,7 @@ export class ApiClient {
         const refreshToken = await this.options.credentials.get('refresh-token');
         if (!refreshToken) {
             await this.options.credentials.clear();
-            throw new ApiResponseError('Authentication has expired', 401, null, false, null);
+            throw new ApiResponseError('Authentication has expired. Recovery: call auth.signin_browser.', 401, null, false, null, browserSigninRecovery);
         }
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
@@ -172,18 +218,19 @@ export class ApiClient {
         catch (error) {
             if (isDefinitiveRefreshRejection(response.status)) {
                 await this.options.credentials.clear();
+                throw new ApiResponseError('Authentication has expired. Recovery: call auth.signin_browser.', response.status, null, false, null, browserSigninRecovery);
             }
             throw error;
         }
         if (!response.ok || envelope.status === 'error') {
             if (isDefinitiveRefreshRejection(response.status)) {
                 await this.options.credentials.clear();
-                throw new ApiResponseError('Authentication has expired', response.status, null, false, envelope);
+                throw new ApiResponseError('Authentication has expired. Recovery: call auth.signin_browser.', response.status, null, false, envelope, browserSigninRecovery);
             }
-            throw new ApiResponseError(envelope.errorModel?.text ?? envelope.message ?? 'Token refresh failed', response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope);
+            throw new ApiResponseError(envelope.errorModel?.text ?? envelope.message ?? 'Token refresh failed', response.status, envelope.errorModel?.code ?? null, retryableResponse(response.status, envelope.errorModel?.retryable), envelope, null);
         }
         if (!isRefreshTokens(envelope.data)) {
-            throw new ApiResponseError('Token refresh response is missing credentials', response.status, null, false, envelope);
+            throw new ApiResponseError('Token refresh response is missing credentials. Recovery: call auth.signin_browser.', response.status, null, false, envelope, browserSigninRecovery);
         }
         await this.options.credentials.set('access-token', envelope.data.accessToken);
         if (envelope.data.refreshToken) {
@@ -196,10 +243,10 @@ export class ApiClient {
             value = await response.json();
         }
         catch {
-            throw new ApiResponseError(`Backend returned a non-JSON response with status ${response.status}`, response.status, null, response.status >= 500, null);
+            throw new ApiResponseError(`Backend returned a non-JSON response with status ${response.status}`, response.status, null, response.status >= 500, null, null);
         }
         if (!isEnvelope(value)) {
-            throw new ApiResponseError('Backend response does not match the Engineering Memory envelope', response.status, null, false, null);
+            throw new ApiResponseError('Backend response does not match the Engineering Memory envelope', response.status, null, false, null, null);
         }
         return value;
     }
@@ -223,6 +270,9 @@ function isEnvelope(value) {
         'message' in candidate &&
         'errorModel' in candidate);
 }
+function retryableResponse(status, declared) {
+    return declared ?? (status === 408 || status === 429 || status >= 500);
+}
 function isRefreshTokens(value) {
     return (value !== null &&
         !Array.isArray(value) &&