@taskforcehq/taskforce 0.3.327 → 0.3.328

package/dist/server/routes/documents.js

@@ -8,6 +8,8 @@
  *   POST   /api/taskforce/context-upload/init
  *   POST   /api/taskforce/context-upload/finalize
  *   POST   /api/taskforce/context-upload
+ *   POST   /api/taskforce/context-upload/draft/promote
+ *   POST   /api/taskforce/context-upload/draft/discard
  *   GET    /api/taskforce/context/:filename
  *   GET    /api/taskforce/documents/:assetId/content
  *   GET    /api/taskforce/context-link
@@ -33,7 +35,7 @@ import { parsePlan } from '../../utils/planParser.js';
 import { getCanonicalDocumentName, getReadableDocumentName, isGeneratedDocumentName } from '../../utils/documentNames.js';
 import { createWorkspaceAssetAccessGuard } from './assetAccess.js';
 import { parseJsonBody } from './primitives.js';
-import { requestHeader, requestRuntimeMode, resolveErrorStatusCode } from './shared.js';
+import { requestHeader, requestHumanActorRef, requestRuntimeMode, requestUserId, resolveErrorStatusCode, } from './shared.js';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
 import { isAiProfileAvatarStorageKey } from '../../utils/aiProfileAvatarPaths.js';
 import { createTaskHttpDurableRouters } from './durableTaskHttpRouters.js';
@@ -110,7 +112,7 @@ async function proxyCloudUserProfileAvatar(req, res, relativePath, contentTypeFo
     }
 }
 export function registerDocumentRoutes(deps) {
-    const { addRoute, core, context, requestWorkspaceId, ensureAdminRole, resolveEffectiveObjectStorageConfig, getObjectStorageClient, resolveStorageWorkspaceId, ensureContextUploadAllowed, parseStorageFolderSegments, buildCanonicalWorkspaceAssetRelativePath, inferAssetKindFromPath, appendStorageTelemetry, scanAndRecordDocument, buildTaskAttachmentPayload, workspaceAssetStore, taskAssetStore, normalizeDocumentPathInput, getAssetMetadata, getCanonicalAssetMetadata, documentRetentionDays, appendDocumentPurgeHistory, markAssetDeleted, isAssetDeleted, clearAssetDeleted, ensureWithinDir, sanitizeDownloadFilename, contentTypeForExt, inferInlineDocumentFromPath, resolveCanonicalDocumentRead, inferWorkspaceIdFromStoragePath, inferTaskIdFromStoragePath, } = deps;
+    const { addRoute, core, context, requestWorkspaceId, ensureAdminRole, resolveEffectiveObjectStorageConfig, getObjectStorageClient, resolveStorageWorkspaceId, ensureContextUploadAllowed, parseStorageFolderSegments, buildCanonicalWorkspaceAssetRelativePath, inferAssetKindFromPath, appendStorageTelemetry, scanAndRecordDocument, buildTaskAttachmentPayload, workspaceAssetStore, taskAssetStore, normalizeDocumentPathInput, getAssetMetadata, getCanonicalAssetMetadata, documentRetentionDays, appendDocumentPurgeHistory, markAssetDeleted, isAssetDeleted, clearAssetDeleted, ensureWithinDir, sanitizeDownloadFilename, contentTypeForExt, inferInlineDocumentFromPath, resolveCanonicalContentRead, inferWorkspaceIdFromStoragePath, inferTaskIdFromStoragePath, } = deps;
     const isTaskAttachmentDurable = (req, workspaceId) => (createTaskHttpDurableRouters({ core, context, req, workspaceId }).attachmentLinks.enabled);
     const durableUploadIdentity = (req, workspaceId, taskId) => {
         const normalizedTaskId = String(taskId || '').trim();
@@ -172,6 +174,69 @@ export function registerDocumentRoutes(deps) {
         return String(url.searchParams.get('workspaceId') || '').trim() || requestWorkspaceId(req);
     };
     const { ensureWorkspaceAssetAccess, isCloudAssetRequest } = createWorkspaceAssetAccessGuard({ core, context });
+    const readTaskDescriptionDraftUpload = (body) => {
+        const draftId = String(body?.draftUploadId || '').trim();
+        const purpose = String(body?.uploadPurpose || '').trim();
+        if (!draftId && !purpose)
+            return null;
+        if (purpose !== 'task-description-draft' || !/^[a-zA-Z0-9-]{16,160}$/.test(draftId)) {
+            throw Object.assign(new Error('Invalid task Description draft upload identity.'), { statusCode: 400 });
+        }
+        return { draftId, purpose };
+    };
+    const recordTaskDescriptionDraftUpload = (input) => {
+        const draft = readTaskDescriptionDraftUpload(input.body);
+        if (!draft || !workspaceAssetStore)
+            return;
+        workspaceAssetStore.recordUploadDraft({
+            workspaceId: input.workspaceId,
+            draftId: draft.draftId,
+            assetId: input.assetId,
+            storageKey: input.storageKey,
+            purpose: draft.purpose,
+            createdByUserId: String(requestUserId(input.req) || '').trim() || 'anonymous',
+        });
+    };
+    const retireOrDeleteTaskDescriptionDraftUploads = async (input) => {
+        if (!workspaceAssetStore)
+            return { total: 0, promoted: 0, discarded: 0 };
+        const records = workspaceAssetStore.listUploadDrafts(input);
+        const now = new Date();
+        const deletedAt = now.toISOString();
+        const purgeAfter = new Date(now.getTime() + documentRetentionDays * 86_400_000).toISOString();
+        let promoted = 0;
+        let discarded = 0;
+        for (const record of records) {
+            const links = workspaceAssetStore.listLinksForAsset(record.assetId, record.workspaceId);
+            if (links.length > 0) {
+                workspaceAssetStore.retireUploadDraft({
+                    workspaceId: record.workspaceId,
+                    draftId: record.draftId,
+                    assetId: record.assetId,
+                    retiredAt: deletedAt,
+                });
+                promoted += 1;
+                continue;
+            }
+            const asset = workspaceAssetStore.get(record.assetId, record.workspaceId);
+            if (asset && !asset.deletedAt) {
+                workspaceAssetStore.assertAssetDeletionAllowed(record.assetId, record.workspaceId);
+                workspaceAssetStore.markDeleted(record.assetId, record.workspaceId, deletedAt, purgeAfter);
+                core.notifyDocumentMetadataMutation(record.workspaceId, [record.storageKey], 'delete');
+            }
+            else if (!asset) {
+                await getObjectStorageClient()?.deleteObject(record.storageKey);
+            }
+            workspaceAssetStore.retireUploadDraft({
+                workspaceId: record.workspaceId,
+                draftId: record.draftId,
+                assetId: record.assetId,
+                retiredAt: deletedAt,
+            });
+            discarded += 1;
+        }
+        return { total: records.length, promoted, discarded };
+    };
     const removeDocumentAttachmentFromTaskAttachments = (attachmentsRaw, asset) => {
         const canonicalDocumentPath = `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`;
         const legacyContextPath = `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`;
@@ -260,6 +325,13 @@ export function registerDocumentRoutes(deps) {
         const relativeToStorage = canonicalAsset.relativePath;
         const relativePath = path.relative(projectRoot, path.join(basePath, relativeToStorage));
         if (objectStorageClient && resolvedObjectStorage.provider === 'r2' && resolvedObjectStorage.r2) {
+            recordTaskDescriptionDraftUpload({
+                req,
+                body,
+                workspaceId,
+                assetId: canonicalAsset.assetId,
+                storageKey: relativeToStorage,
+            });
             const uploadUrl = objectStorageClient.createSignedPutUrl(relativeToStorage, resolvedObjectStorage.r2.signedUploadTtlSeconds, String(mimeType || 'application/octet-stream'));
             appendStorageTelemetry('upload.initiated', {
                 path: relativeToStorage,
@@ -345,8 +417,19 @@ export function registerDocumentRoutes(deps) {
                 provider: 'r2',
                 workspaceId: inferWorkspaceIdFromStoragePath(relativeToStorage),
                 taskId: durableTaskAttachment ? null : taskId,
-                originalName: typeof body?.originalName === 'string' ? body.originalName.trim() : null
+                originalName: typeof body?.originalName === 'string' ? body.originalName.trim() : null,
+                actorRef: requestHumanActorRef(req),
             });
+            const finalizedAsset = workspaceAssetStore?.getByStorageKey(relativeToStorage, workspaceId);
+            if (finalizedAsset) {
+                recordTaskDescriptionDraftUpload({
+                    req,
+                    body,
+                    workspaceId,
+                    assetId: finalizedAsset.assetId,
+                    storageKey: relativeToStorage,
+                });
+            }
             if (durableTaskAttachment && taskId) {
                 attachUploadedAssetThroughDurableBoundary({
                     req,
@@ -456,7 +539,8 @@ export function registerDocumentRoutes(deps) {
                 provider: 'r2',
                 workspaceId,
                 taskId: durableTaskAttachment ? null : normalizedTaskId,
-                originalName: safeOriginal || actualFilename
+                originalName: safeOriginal || actualFilename,
+                actorRef: requestHumanActorRef(req),
             });
             appendStorageTelemetry('upload.completed', {
                 path: relativeToStorage,
@@ -476,7 +560,8 @@ export function registerDocumentRoutes(deps) {
                 provider: 'local',
                 workspaceId,
                 taskId: durableTaskAttachment ? null : normalizedTaskId,
-                originalName: safeOriginal || actualFilename
+                originalName: safeOriginal || actualFilename,
+                actorRef: requestHumanActorRef(req),
             });
             appendStorageTelemetry('upload.completed', {
                 path: relativeToStorage,
@@ -494,6 +579,16 @@ export function registerDocumentRoutes(deps) {
                 caption: safeOriginal || actualFilename,
             });
         }
+        const uploadedAsset = workspaceAssetStore?.getByStorageKey(relativeToStorage, workspaceId);
+        if (uploadedAsset) {
+            recordTaskDescriptionDraftUpload({
+                req,
+                body,
+                workspaceId,
+                assetId: uploadedAsset.assetId,
+                storageKey: relativeToStorage,
+            });
+        }
         res.writeHead(200, { 'Content-Type': 'application/json' });
         const attachment = buildTaskAttachmentPayload(relativeToStorage, {
             caption: safeOriginal || actualFilename,
@@ -508,6 +603,40 @@ export function registerDocumentRoutes(deps) {
             })
         }));
     });
+    addRoute('POST', '/api/taskforce/context-upload/draft/promote', async (req, res) => {
+        const body = await parseJsonBody(req);
+        const workspaceId = resolveStorageWorkspaceId(req, body);
+        const draft = readTaskDescriptionDraftUpload(body);
+        if (!workspaceId || !draft) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'workspaceId and draft upload identity are required.' }));
+            return;
+        }
+        const summary = await retireOrDeleteTaskDescriptionDraftUploads({
+            workspaceId,
+            draftId: draft.draftId,
+            createdByUserId: String(requestUserId(req) || '').trim() || 'anonymous',
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, ...summary }));
+    });
+    addRoute('POST', '/api/taskforce/context-upload/draft/discard', async (req, res) => {
+        const body = await parseJsonBody(req);
+        const workspaceId = resolveStorageWorkspaceId(req, body);
+        const draft = readTaskDescriptionDraftUpload(body);
+        if (!workspaceId || !draft) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'workspaceId and draft upload identity are required.' }));
+            return;
+        }
+        const summary = await retireOrDeleteTaskDescriptionDraftUploads({
+            workspaceId,
+            draftId: draft.draftId,
+            createdByUserId: String(requestUserId(req) || '').trim() || 'anonymous',
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, ...summary }));
+    });
     addRoute('GET', '/api/taskforce/context/:filename', async (req, res, params) => {
         const resolvedObjectStorage = resolveEffectiveObjectStorageConfig();
         const objectStorageClient = getObjectStorageClient();
@@ -556,8 +685,8 @@ export function registerDocumentRoutes(deps) {
             ? `attachment; filename="${resolvedDownloadName.replace(/"/g, '')}"`
             : 'inline';
         const shouldProxyInlineDocument = !forceDownload && (canonicalAsset?.kind === 'document' || inferInlineDocumentFromPath(normalizedRelative));
-        if (canonicalAsset?.kind === 'document' && !canonicalAsset.deletedAt) {
-            const response = await resolveCanonicalDocumentRead({
+        if (canonicalAsset && !canonicalAsset.deletedAt && (canonicalAsset.kind === 'document' || !filePath)) {
+            const response = await resolveCanonicalContentRead({
                 asset: canonicalAsset,
                 forceDownload,
                 requestedFilename
@@ -567,6 +696,11 @@ export function registerDocumentRoutes(deps) {
                 res.end('Context file not found');
                 return;
             }
+            if (response.statusCode === 409) {
+                res.writeHead(409, response.headers || { 'Content-Type': 'application/json' });
+                res.end(response.body);
+                return;
+            }
             if (forceDownload && response.statusCode === 302 && response.headers?.Location) {
                 res.writeHead(302, { Location: response.headers.Location });
                 res.end();
@@ -659,7 +793,7 @@ export function registerDocumentRoutes(deps) {
             res.end('Document scan pending');
             return;
         }
-        const response = await resolveCanonicalDocumentRead({
+        const response = await resolveCanonicalContentRead({
             asset,
             forceDownload,
             requestedFilename
@@ -669,6 +803,11 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Document content not found' }));
             return;
         }
+        if (response.statusCode === 409) {
+            res.writeHead(409, response.headers || { 'Content-Type': 'application/json' });
+            res.end(response.body);
+            return;
+        }
         if (forceDownload && response.statusCode === 302 && response.headers?.Location) {
             res.writeHead(302, { Location: response.headers.Location });
             res.end();
@@ -791,6 +930,12 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
             return;
         }
+        const workspaceId = requestWorkspaceId(req);
+        const draftExpiry = new Date(Date.now() - 30 * 86_400_000).toISOString();
+        const draftSummary = await retireOrDeleteTaskDescriptionDraftUploads({
+            workspaceId,
+            createdBefore: draftExpiry,
+        });
         const { basePath } = core.getPaths();
         const summary = await purgeExpiredDocuments({
             basePath,
@@ -804,7 +949,7 @@ export function registerDocumentRoutes(deps) {
             provider: resolveEffectiveObjectStorageConfig().provider
         });
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true, ...summary }));
+        res.end(JSON.stringify({ success: true, ...summary, draftUploads: draftSummary }));
     });
     addRoute('GET', '/api/taskforce/documents', async (req, res) => {
         const workspaceId = requestWorkspaceIdWithQuery(req);
@@ -1059,7 +1204,7 @@ export function registerDocumentRoutes(deps) {
             core.updateTask(targetId, {
                 attachments: [...(Array.isArray(task.attachments) ? task.attachments : []), payload],
             }, workspaceId, {
-                actorRef: 'user',
+                actorRef: requestHumanActorRef(req),
                 saveSource: 'manual',
             });
         }
@@ -1124,7 +1269,7 @@ export function registerDocumentRoutes(deps) {
                 else {
                     const updatedAttachments = removeDocumentAttachmentFromTaskAttachments(task.attachments, asset);
                     core.updateTask(taskId, { attachments: updatedAttachments }, workspaceId, {
-                        actorRef: 'user',
+                        actorRef: requestHumanActorRef(req),
                         saveSource: 'manual'
                     });
                 }
@@ -1280,7 +1425,8 @@ export function registerDocumentRoutes(deps) {
                         contentType: 'text/markdown; charset=utf-8',
                         provider: 'r2',
                         workspaceId: assetWorkspaceId,
-                        originalName: metadata.logicalName || metadata.originalFilename || path.basename(normalizedStoragePath)
+                        originalName: metadata.logicalName || metadata.originalFilename || path.basename(normalizedStoragePath),
+                        actorRef: requestHumanActorRef(req),
                     });
                     clearAssetDeleted(normalizedStoragePath);
                     const version = workspaceAssetStore
@@ -1336,7 +1482,8 @@ export function registerDocumentRoutes(deps) {
                     contentType: 'text/markdown; charset=utf-8',
                     provider: 'local',
                     workspaceId: assetWorkspaceId,
-                    originalName: path.basename(normalizedStoragePath)
+                    originalName: path.basename(normalizedStoragePath),
+                    actorRef: requestHumanActorRef(req),
                 });
                 clearAssetDeleted(normalizedStoragePath);
                 version = workspaceAssetStore

package/dist/server/routes/durableTaskHttpRouters.d.ts

@@ -53,6 +53,7 @@ export declare function createTaskHttpDurableRouters(input: {
         replace(args: {
             taskId: string;
             links: readonly import("../../sync/v3/workspaceSyncV3NestedTaskCodecs.js").WorkspaceSyncV3TaskAttachmentLink[];
+            cardCoverAssetId?: string | null;
         }): {
             state: "pending" | "committed";
             route: "local-outbox" | "cloud-acceptance";
@@ -77,6 +78,7 @@ export declare function createTaskHttpDurableRouters(input: {
         replace(args: {
             taskId: string;
             links: readonly import("../../sync/v3/workspaceSyncV3NestedTaskCodecs.js").WorkspaceSyncV3TaskAttachmentLink[];
+            cardCoverAssetId?: string | null;
         }): {
             state: "pending" | "committed";
             route: "local-outbox" | "cloud-acceptance";

package/dist/server/routes/durableTaskHttpRouters.js

@@ -4,12 +4,12 @@ import { createDurableTaskHttpRootMutationRouter } from '../../sync/v3/durableTa
 import { createDurableTaskCommentMutationRouter } from '../../sync/v3/durableTaskCommentMutationRouter.js';
 import { createDurableTaskChecklistMutationRouter } from '../../sync/v3/durableTaskChecklistMutationRouter.js';
 import { createDurableTaskAttachmentLinksMutationRouter } from '../../sync/v3/durableTaskAttachmentLinksMutationRouter.js';
-import { requestHeader, requestRuntimeMode, requestUserId } from './shared.js';
+import { requestHeader, requestHumanActorRef, requestRuntimeMode } from './shared.js';
 export function createTaskHttpDurableRouters(input) {
     const { core, context, req, workspaceId } = input;
     const runtimeMode = context.authConfig?.runtimeMode === 'cloud' ? 'cloud' : requestRuntimeMode(req);
     const parentOperationId = requestHeader(req, 'x-taskforce-operation-id', '').trim();
-    const actorRef = runtimeMode === 'cloud' ? (String(requestUserId(req) || '').trim() || 'user') : 'user';
+    const actorRef = requestHumanActorRef(req);
     const createRootRouter = (operationId = parentOperationId, deferPostCommitNotification) => createDurableTaskHttpRootMutationRouter({
         core,
         runtimeMode,

package/dist/server/routes/localService.js

@@ -185,6 +185,7 @@ export function registerLocalServiceRoutes(deps) {
             endpoint: context.endpoint?.() || null,
             projectIdentity: context.projectIdentity,
             dataIdentity: context.ownershipKey,
+            cloudTarget: context.cloudTarget,
             transports: ['streamable-http'],
             health: {
                 lifecycle: context.sessions.state(),
@@ -279,6 +280,7 @@ export function registerLocalServiceRoutes(deps) {
             generation: context.generation,
             protocolVersion: context.protocolVersion,
             ownerPid: context.ownerPid,
+            cloudTarget: context.cloudTarget,
             sessions: context.sessions.list(),
             ...(context.diagnostics?.() || {}),
         });

package/dist/server/routes/primitives.d.ts

@@ -4,6 +4,7 @@ import type { ResolvedObjectStorageConfig } from '../../storage/objectStorage.js
 import type { LocalSyncCoordinatorRouteServices } from '../../sync/coordinator/localSyncCoordinatorRouteServices.js';
 import type { WorkspaceSyncServerDataServices } from '../../sync/engine/workspaceSyncServerDataServices.js';
 import type { LocalServiceSessionManager } from '../localServiceSessions.js';
+import type { LocalServiceCloudTarget } from '../../config/localServiceCloudTarget.js';
 export interface LocalServiceRouteContext {
     generation: string;
     protocolVersion: string;
@@ -11,6 +12,7 @@ export interface LocalServiceRouteContext {
     ownerPid: number;
     bootstrapCapability: string;
     ownershipKey: string;
+    cloudTarget: LocalServiceCloudTarget;
     projectIdentity: string;
     operationClientId: string;
     sessions: LocalServiceSessionManager;

package/dist/server/routes/shared.d.ts

@@ -11,6 +11,7 @@ import type { McpAccessTokenAuthResult, McpOAuthAccessTokenAuthResult, McpAccess
 import { type RouteContext } from './primitives.js';
 import { type AiProfileBootstrapConfig } from '../../mcp/aiProfileBootstrap.js';
 import type { AiProfileSeatScope } from '../../shared/aiProfileSeatScope.js';
+import { type RequestPerformanceDiagnostics } from '../../storage/postgresRequestDiagnostics.js';
 export declare function resolveErrorStatusCode(error: unknown, fallback?: number): number;
 export declare function buildCloudMcpProfileConnectionId(input: {
     oauth?: McpOAuthAccessTokenAuthResult | null;
@@ -19,6 +20,7 @@ export declare function buildCloudMcpProfileConnectionId(input: {
 }): string | null;
 export declare const BOOTSTRAP_ROUTE_SLOW_THRESHOLD_MS = 1500;
 export declare const BOOTSTRAP_ROUTE_SEVERE_THRESHOLD_MS = 5000;
+export declare const TASKFORCE_PERFORMANCE_TRACE_HEADER = "x-taskforce-performance-trace";
 export type ServerTimingMetric = {
     name: string;
     durationMs: number;
@@ -31,6 +33,17 @@ export declare function serializeJsonWithTiming(payload: unknown, startedAt?: nu
     byteLength: number;
     durationMs: number;
 };
+export declare function runWithPerformanceTrace<T>(req: IncomingMessage, callback: () => T): T;
+export declare function currentPerformanceTraceDiagnostics(): RequestPerformanceDiagnostics | null;
+export declare function performanceTraceServerTimingMetrics(diagnostics: RequestPerformanceDiagnostics | null): ServerTimingMetric[];
+export declare function setPerformanceTraceHeaders(res: ServerResponse, diagnostics: RequestPerformanceDiagnostics | null, responseBytes: number): void;
+export declare function respondWithPerformanceTraceJson(input: {
+    req: IncomingMessage;
+    res: ServerResponse;
+    route: string;
+    workspaceId: string;
+    load: () => unknown;
+}): void;
 export declare function requestBootstrapTraceId(req: IncomingMessage): string;
 export declare function logSlowBootstrapRoute(input: {
     route: string;
@@ -47,6 +60,7 @@ export declare function buildCloudMcpRuntimeAuth(input: {
         authenticatedViaToken: McpAccessTokenAuthResult | null;
         authenticatedViaOAuth: McpOAuthAccessTokenAuthResult | null;
         userId: string | null;
+        aiProfileIdentityAsserted?: boolean;
     } & Required<AiProfileBootstrapConfig>;
     requestHeader: (req: IncomingMessage, name: string, fallback?: string) => string;
     requestId?: string | null;
@@ -57,6 +71,7 @@ export declare function buildCloudMcpRuntimeAuth(input: {
     tokenId?: string | null;
     aiProfileToken?: AiProfileBootstrapConfig['aiProfileToken'];
     aiProfileId?: string | null;
+    aiProfileIdentityAsserted?: boolean;
     aiProfileName?: AiProfileBootstrapConfig['aiProfileName'];
     aiProfileIcon?: AiProfileBootstrapConfig['aiProfileIcon'];
     aiProfileColor?: AiProfileBootstrapConfig['aiProfileColor'];
@@ -79,6 +94,7 @@ export type CloudMcpRequestAuth = {
     authenticatedViaOAuth: McpOAuthAccessTokenAuthResult | null;
     userId: string | null;
     aiProfileId?: string | null;
+    aiProfileIdentityAsserted?: boolean;
 } & Required<AiProfileBootstrapConfig>;
 export declare function makeAuthenticateCloudMcpRequest(core: TaskforceCore, deps: {
     resolveAuthenticatedUserId: (req: IncomingMessage) => string;
@@ -101,6 +117,14 @@ export declare function requestRuntimeMode(req: IncomingMessage): 'local' | 'clo
 export declare function requestRole(req: IncomingMessage): string;
 export declare function requestSystemRole(req: IncomingMessage): 'system_admin' | 'user';
 export declare function requestUserId(req: IncomingMessage): string;
+/**
+ * Resolve the human actor recorded by ordinary HTTP mutations. The standalone
+ * server has already replaced this header with authenticated cloud identity
+ * when available; local signed-in clients provide the same account id through
+ * the request-scoped mutation header. Anonymous sessions retain the legacy
+ * generic actor for compatibility.
+ */
+export declare function requestHumanActorRef(req: IncomingMessage): string;
 export declare function makeRequestWorkspaceId(core: TaskforceCore, context: RouteContext): (req: IncomingMessage) => string;
 export declare function makeResolveAuthenticatedUserId(core: TaskforceCore, context: RouteContext, requestWorkspaceId: (req: IncomingMessage) => string): (req: IncomingMessage) => string;
 export declare function makeResolveAuthenticatedMutationUserId(core: TaskforceCore, context: RouteContext, requestWorkspaceId: (req: IncomingMessage) => string): (req: IncomingMessage) => string;