@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/server/routes/localService.js

@@ -0,0 +1,444 @@
+import { createHash, timingSafeEqual } from 'crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { parseMcpClientId } from '../../mcp/clientRegistry.js';
+import { createTaskforceMcpServer } from '../../mcp/runtime.js';
+import { MCP_TOOL_PROFILES } from '../../mcp/toolRegistry.js';
+import { parseJsonBody } from './primitives.js';
+import { LocalServiceSessionError } from '../localServiceSessions.js';
+const API_BASE = '/api/taskforce/local-service/v1';
+const ALLOWED_SCOPES = new Set(['tasks:read', 'tasks:write', 'workspace:read']);
+const MAX_REGISTRATION_BODY_BYTES = 32 * 1024;
+const MAX_MCP_BODY_BYTES = 1024 * 1024;
+function writeJson(res, statusCode, body) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(body));
+}
+function fail(res, statusCode, error, code) {
+    writeJson(res, statusCode, { error, code });
+}
+function isLoopback(req) {
+    const address = String(req.socket.remoteAddress || '').toLowerCase();
+    return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+function guardLocalRequest(req, res) {
+    if (!isLoopback(req)) {
+        fail(res, 403, 'Local service requests must originate from loopback.', 'LOOPBACK_REQUIRED');
+        return false;
+    }
+    if (String(req.headers.origin || '').trim()) {
+        fail(res, 403, 'Browser-origin requests are not accepted by the local service.', 'BROWSER_ORIGIN_REJECTED');
+        return false;
+    }
+    return true;
+}
+function header(req, name) {
+    const value = req.headers[name.toLowerCase()];
+    return Array.isArray(value) ? String(value[0] || '') : String(value || '');
+}
+function requestCorrelation(req, name) {
+    const value = header(req, name).trim();
+    return value && value.length <= 128 && /^[A-Za-z0-9._:-]+$/.test(value) ? value : null;
+}
+function constantTimeEqual(left, right) {
+    const leftDigest = createHash('sha256').update(left, 'utf8').digest();
+    const rightDigest = createHash('sha256').update(right, 'utf8').digest();
+    return timingSafeEqual(leftDigest, rightDigest);
+}
+function hasBootstrapCapability(req, context) {
+    const supplied = header(req, 'x-taskforce-local-service-capability').trim();
+    return Boolean(supplied) && constantTimeEqual(supplied, context.bootstrapCapability);
+}
+function bearer(req) {
+    const authorization = header(req, 'authorization').trim();
+    const match = authorization.match(/^Bearer\s+(.+)$/i);
+    return match?.[1]?.trim() || '';
+}
+function authenticateSession(req, res, context) {
+    const token = bearer(req);
+    if (!token || constantTimeEqual(token, context.bootstrapCapability)) {
+        fail(res, 401, 'A valid local service session bearer is required.', 'SESSION_AUTH_REQUIRED');
+        return null;
+    }
+    const session = context.sessions.authenticate(token);
+    if (!session) {
+        fail(res, 401, 'The local service session is invalid or expired.', 'SESSION_INVALID');
+        return null;
+    }
+    return session;
+}
+function normalizeRegistration(body, context) {
+    const clientId = parseMcpClientId(body?.clientId);
+    const connectionInstance = String(body?.connectionInstance || '').trim();
+    const workspaceId = String(body?.workspaceId || '').trim();
+    const protocolVersion = String(body?.protocolVersion || '').trim();
+    const generation = String(body?.generation || '').trim();
+    const toolProfile = String(body?.toolProfile || '').trim().toLowerCase();
+    const permissions = Array.isArray(body?.permissions)
+        ? Array.from(new Set(body.permissions.map((value) => String(value).trim())))
+        : [];
+    const profileToken = String(body?.profileToken || '').trim();
+    if (!clientId)
+        throw new LocalServiceSessionError('clientId is not supported.', 400, 'CLIENT_ID_INVALID');
+    if (!connectionInstance || connectionInstance.length > 200) {
+        throw new LocalServiceSessionError('connectionInstance is required.', 400, 'CONNECTION_INSTANCE_INVALID');
+    }
+    if (!workspaceId)
+        throw new LocalServiceSessionError('workspaceId is required.', 400, 'WORKSPACE_REQUIRED');
+    if (protocolVersion !== context.protocolVersion) {
+        throw new LocalServiceSessionError('Local service protocol version mismatch.', 409, 'PROTOCOL_VERSION_MISMATCH');
+    }
+    if (generation !== context.generation) {
+        throw new LocalServiceSessionError('Local service generation mismatch.', 409, 'GENERATION_MISMATCH');
+    }
+    if (!MCP_TOOL_PROFILES.includes(toolProfile)) {
+        throw new LocalServiceSessionError('toolProfile is invalid.', 400, 'TOOL_PROFILE_INVALID');
+    }
+    if (permissions.length === 0 || permissions.some((scope) => !ALLOWED_SCOPES.has(scope))) {
+        throw new LocalServiceSessionError('permissions must contain only supported MCP scopes.', 400, 'PERMISSIONS_INVALID');
+    }
+    if (profileToken.length > 512) {
+        throw new LocalServiceSessionError('profileToken is invalid.', 400, 'PROFILE_TOKEN_INVALID');
+    }
+    return {
+        clientId,
+        connectionInstance,
+        workspaceId,
+        permissions: permissions,
+        toolProfile,
+        protocolVersion,
+        generation,
+        profileToken: profileToken || null,
+    };
+}
+function lookupBoundOperation(core, context, session, operationId, req) {
+    const url = new URL(req.url || '/', 'http://127.0.0.1');
+    const expectedMutationKind = String(url.searchParams.get('mutationKind') || '').trim() || null;
+    const expectedPayloadFingerprint = String(url.searchParams.get('payloadFingerprint') || '').trim() || null;
+    const binding = context.sessions.getOperationBinding(session.id, operationId, {
+        mutationKind: expectedMutationKind,
+        payloadFingerprint: expectedPayloadFingerprint,
+    });
+    if (!binding)
+        return null;
+    const row = core.getDatabaseAdapter().prepare(`
+        SELECT status, authoritative_response_json, created_at,
+               mutation_kind, payload_fingerprint
+        FROM workspace_sync_outbox
+        WHERE tenant_id = ?
+          AND workspace_id = ?
+          AND client_id = ?
+          AND operation_id = ?
+        LIMIT 1
+    `).get(core.getTenantId(), session.workspaceId, context.operationClientId, operationId);
+    if (!row)
+        return null;
+    const responseJson = typeof row.authoritative_response_json === 'string'
+        ? row.authoritative_response_json
+        : null;
+    if (responseJson && Buffer.byteLength(responseJson, 'utf8') > MAX_MCP_BODY_BYTES) {
+        throw new LocalServiceSessionError('Operation response exceeds the local service limit.', 500, 'OPERATION_RESPONSE_INVALID');
+    }
+    return {
+        operationId,
+        status: row.status,
+        createdAt: row.created_at,
+        mutationKind: row.mutation_kind,
+        payloadFingerprint: binding.payloadFingerprint,
+        durablePayloadFingerprint: row.payload_fingerprint,
+        response: responseJson ? JSON.parse(responseJson) : null,
+    };
+}
+function auditShutdown(core, context, input) {
+    try {
+        core.addAdminAuditLog({
+            action: `local-service-shutdown-${input.outcome}`,
+            actorUserId: 'local-service-owner',
+            actorRole: 'owner',
+            workspaceId: core.resolvePreferredWorkspaceId({ allowDefault: true }) || 'default',
+            details: {
+                mode: input.mode,
+                reason: input.reason || null,
+                generation: context.generation,
+                ownerPid: context.ownerPid,
+                activeSessions: input.activeSessions,
+                inFlight: input.inFlight,
+            },
+        });
+    }
+    catch (error) {
+        console.error('[Taskforce] Failed to persist local service shutdown audit:', error);
+    }
+}
+export function registerLocalServiceRoutes(deps) {
+    const context = deps.context;
+    if (!context)
+        return;
+    deps.addRoute('GET', `${API_BASE}/readiness`, async (req, res) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        writeJson(res, 200, {
+            ready: context.sessions.state() === 'accepting',
+            protocolVersion: context.protocolVersion,
+            appVersion: context.appVersion,
+            generation: context.generation,
+            pid: context.ownerPid,
+            endpoint: context.endpoint?.() || null,
+            projectIdentity: context.projectIdentity,
+            dataIdentity: context.ownershipKey,
+            transports: ['streamable-http'],
+            health: {
+                lifecycle: context.sessions.state(),
+                activeSessions: context.sessions.activeCount(),
+                inFlightRequests: context.sessions.inFlightCount(),
+            },
+        });
+    });
+    deps.addRoute('POST', `${API_BASE}/sessions`, async (req, res) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        if (!hasBootstrapCapability(req, context)) {
+            fail(res, 401, 'The descriptor bootstrap capability is required.', 'BOOTSTRAP_AUTH_REQUIRED');
+            return;
+        }
+        try {
+            const body = await parseJsonBody(req, MAX_REGISTRATION_BODY_BYTES);
+            const requestedWorkspaceId = String(body?.workspaceId || '').trim();
+            const workspaceId = requestedWorkspaceId && requestedWorkspaceId.toLowerCase() !== 'default'
+                ? requestedWorkspaceId
+                : deps.core.resolvePreferredWorkspaceId({ allowDefault: false }) || '';
+            const normalized = normalizeRegistration({ ...body, workspaceId }, context);
+            const { profileToken, ...registration } = normalized;
+            if (!deps.core.workspaceExists(registration.workspaceId)) {
+                fail(res, 404, 'Workspace not found.', 'WORKSPACE_NOT_FOUND');
+                return;
+            }
+            const profile = profileToken
+                ? deps.core.getAiProfileByToken({
+                    workspaceId: registration.workspaceId,
+                    profileToken,
+                    seatScope: 'local_unmetered',
+                })
+                : null;
+            if (profileToken && !profile) {
+                fail(res, 401, 'AI profile token is invalid for this workspace.', 'PROFILE_TOKEN_INVALID');
+                return;
+            }
+            const created = context.sessions.create(registration, { aiProfileId: profile?.id || null });
+            writeJson(res, 201, { session: created.session, bearerToken: created.token });
+        }
+        catch (error) {
+            const statusCode = error instanceof LocalServiceSessionError ? error.statusCode : Number(error?.statusCode) || 400;
+            const code = error instanceof LocalServiceSessionError ? error.code : 'REGISTRATION_INVALID';
+            fail(res, statusCode, String(error?.message || 'Invalid registration.'), code);
+        }
+    });
+    deps.addRoute('DELETE', `${API_BASE}/sessions/:id`, async (req, res, params) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        const session = authenticateSession(req, res, context);
+        if (!session)
+            return;
+        if (session.id !== params.id) {
+            fail(res, 403, 'A session may revoke only itself.', 'SESSION_SCOPE_MISMATCH');
+            return;
+        }
+        context.sessions.revoke(session.id);
+        res.writeHead(204, { 'Cache-Control': 'no-store' });
+        res.end();
+    });
+    deps.addRoute('GET', `${API_BASE}/operations/:operationId`, async (req, res, params) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        const session = authenticateSession(req, res, context);
+        if (!session)
+            return;
+        try {
+            const operation = lookupBoundOperation(deps.core, context, session, params.operationId, req);
+            if (!operation) {
+                fail(res, 404, 'Operation not found.', 'OPERATION_NOT_FOUND');
+                return;
+            }
+            writeJson(res, 200, operation);
+        }
+        catch (error) {
+            if (error instanceof LocalServiceSessionError) {
+                fail(res, error.statusCode, error.message, error.code);
+                return;
+            }
+            throw error;
+        }
+    });
+    deps.addRoute('GET', `${API_BASE}/diagnostics`, async (req, res) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        if (!hasBootstrapCapability(req, context)) {
+            fail(res, 401, 'Administrative capability required.', 'ADMIN_AUTH_REQUIRED');
+            return;
+        }
+        writeJson(res, 200, {
+            generation: context.generation,
+            protocolVersion: context.protocolVersion,
+            ownerPid: context.ownerPid,
+            sessions: context.sessions.list(),
+            ...(context.diagnostics?.() || {}),
+        });
+    });
+    deps.addRoute('POST', `${API_BASE}/shutdown`, async (req, res) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        if (!hasBootstrapCapability(req, context)) {
+            fail(res, 401, 'Administrative capability required.', 'ADMIN_AUTH_REQUIRED');
+            return;
+        }
+        const body = await parseJsonBody(req, MAX_REGISTRATION_BODY_BYTES);
+        const mode = String(body?.mode || 'refuse');
+        if (body?.intent !== 'administrative-stop'
+            || body?.pid !== context.ownerPid
+            || body?.generation !== context.generation
+            || !['refuse', 'drain', 'force'].includes(mode)) {
+            fail(res, 409, 'Shutdown owner, generation, mode, or intent mismatch.', 'SHUTDOWN_INTENT_MISMATCH');
+            return;
+        }
+        const activeSessions = context.sessions.activeCount();
+        const inFlight = context.sessions.inFlightCount();
+        try {
+            context.sessions.beginShutdown(mode);
+        }
+        catch (error) {
+            const sessionError = error;
+            auditShutdown(deps.core, context, {
+                mode,
+                outcome: 'refused',
+                reason: sessionError.code || 'SHUTDOWN_REFUSED',
+                activeSessions,
+                inFlight,
+            });
+            fail(res, sessionError.statusCode || 409, sessionError.message, sessionError.code || 'SHUTDOWN_REFUSED');
+            return;
+        }
+        if (mode === 'drain') {
+            const drained = await context.sessions.waitForDrain(10_000);
+            if (!drained) {
+                context.sessions.cancelDrain();
+                auditShutdown(deps.core, context, {
+                    mode,
+                    outcome: 'refused',
+                    reason: 'DRAIN_TIMEOUT',
+                    activeSessions,
+                    inFlight,
+                });
+                fail(res, 409, 'Active MCP requests did not drain before the deadline.', 'DRAIN_TIMEOUT');
+                return;
+            }
+            context.sessions.revokeAll();
+        }
+        auditShutdown(deps.core, context, { mode, outcome: 'accepted', activeSessions, inFlight });
+        writeJson(res, 202, { accepted: true, mode, activeSessions, inFlight });
+        setImmediate(() => context.requestShutdown(mode));
+    });
+    deps.addRoute('POST', '/mcp', async (req, res) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        const session = authenticateSession(req, res, context);
+        if (!session)
+            return;
+        let runtime = null;
+        let requestStarted = false;
+        let unregisterCancellation = () => { };
+        let resolveCancellation = () => { };
+        const cancellation = new Promise((resolve) => { resolveCancellation = resolve; });
+        try {
+            const body = await parseJsonBody(req, MAX_MCP_BODY_BYTES);
+            const cancellationId = body?.method === 'notifications/cancelled'
+                && (typeof body?.params?.requestId === 'string' || typeof body?.params?.requestId === 'number')
+                ? body.params.requestId
+                : null;
+            if (cancellationId !== null) {
+                const correlationId = requestCorrelation(req, 'x-taskforce-mcp-cancel-correlation');
+                if (correlationId)
+                    context.sessions.cancelRequest(session.id, correlationId);
+                res.writeHead(202, { 'Cache-Control': 'no-store' });
+                res.end();
+                return;
+            }
+            context.sessions.beginRequest(session.id);
+            requestStarted = true;
+            const correlationId = requestCorrelation(req, 'x-taskforce-mcp-request-correlation');
+            let cancelled = false;
+            if (correlationId) {
+                unregisterCancellation = context.sessions.registerCancellation(session.id, correlationId, () => {
+                    cancelled = true;
+                    resolveCancellation();
+                });
+            }
+            if (cancelled)
+                return;
+            runtime = (deps.createMcpServer || createTaskforceMcpServer)({
+                projectRoot: deps.core.getPaths().projectRoot,
+                tenantId: deps.core.getTenantId(),
+                workspaceId: session.workspaceId,
+                core: deps.core,
+                serverName: 'taskforce-local-service',
+                logStartup: false,
+                runtimeMode: 'local',
+                operationIdentityScope: {
+                    generation: context.generation,
+                    sessionId: session.id,
+                    connectionInstance: session.connectionInstance,
+                },
+                toolProfile: session.toolProfile,
+                auth: {
+                    scopes: session.permissions,
+                    userId: session.aiProfileId || `local-session:${session.id}`,
+                    tokenId: session.id,
+                    aiProfileId: session.aiProfileId,
+                    mcpClientId: session.clientId,
+                    mcpConnectionId: session.connectionInstance,
+                    actorType: 'local',
+                    requestId: header(req, 'x-request-id').trim() || undefined,
+                    ip: req.socket.remoteAddress || null,
+                    userAgent: header(req, 'user-agent').trim() || null,
+                },
+                onAiProfileBound: (profileId) => context.sessions.bindAiProfile(session.id, profileId),
+                onOperationAccepted: (operation) => context.sessions.recordOperation({
+                    sessionId: session.id,
+                    ...operation,
+                }),
+            });
+            const transport = deps.createMcpTransport?.() || new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            await runtime.server.connect(transport);
+            if (cancelled)
+                return;
+            const handling = transport.handleRequest(req, res, body);
+            await Promise.race([handling, cancellation]);
+            if (cancelled)
+                void handling.catch(() => undefined);
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                const statusCode = error instanceof LocalServiceSessionError ? error.statusCode : 500;
+                const code = error instanceof LocalServiceSessionError ? error.code : 'MCP_TRANSPORT_FAILURE';
+                fail(res, statusCode, statusCode >= 500 ? 'MCP transport failure.' : String(error.message), code);
+            }
+        }
+        finally {
+            unregisterCancellation();
+            await runtime?.server.close().catch(() => undefined);
+            if (requestStarted)
+                context.sessions.endRequest(session.id);
+        }
+    });
+    const rejectUnsupportedMcpMethod = async (req, res) => {
+        if (!guardLocalRequest(req, res))
+            return;
+        if (!authenticateSession(req, res, context))
+            return;
+        fail(res, 405, 'Only POST is supported by the stateless local MCP transport.', 'MCP_METHOD_NOT_ALLOWED');
+    };
+    deps.addRoute('GET', '/mcp', rejectUnsupportedMcpMethod);
+    deps.addRoute('HEAD', '/mcp', rejectUnsupportedMcpMethod);
+    deps.addRoute('DELETE', '/mcp', rejectUnsupportedMcpMethod);
+}

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

@@ -0,0 +1,11 @@
+import { applyTaskforceUiUpdate, type UiUpdateApplyResult } from '../../update/uiUpdateService.js';
+import { type TaskforceUpdateStatus, type TaskforceUpdateTarget } from '../../update/updateStatus.js';
+import { type RouteContext, type RouteHandler } from './primitives.js';
+export interface LocalUpdateRouteDependencies {
+    addRoute: (method: string, path: string, handler: RouteHandler) => void;
+    context: RouteContext;
+    getStatus?: () => Promise<TaskforceUpdateStatus>;
+    applyUpdate?: (target: TaskforceUpdateTarget, dependencies: Parameters<typeof applyTaskforceUiUpdate>[1]) => Promise<UiUpdateApplyResult>;
+    platform?: NodeJS.Platform;
+}
+export declare function registerLocalUpdateRoutes(dependencies: LocalUpdateRouteDependencies): void;

package/dist/server/routes/localUpdate.js

@@ -0,0 +1,154 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getTaskforceRuntimeVersion } from '../../mcp/localCliHealth.js';
+import { applyTaskforceUiUpdate, buildUiUpdateOverview, } from '../../update/uiUpdateService.js';
+import { getTaskforceUpdateStatus, } from '../../update/updateStatus.js';
+import { parseJsonBody } from './primitives.js';
+const JSON_HEADERS = {
+    'Content-Type': 'application/json',
+    'Cache-Control': 'no-store',
+};
+function runtimePackageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+}
+function createStatusProvider() {
+    return () => getTaskforceUpdateStatus({
+        app: {
+            target: 'app',
+            version: getTaskforceRuntimeVersion(),
+            runtimeMode: 'local',
+            packageRoot: runtimePackageRoot(),
+        },
+    });
+}
+function writeJson(res, statusCode, body) {
+    res.writeHead(statusCode, JSON_HEADERS);
+    res.end(JSON.stringify(body));
+}
+function isSameOriginBrowserRequest(req) {
+    const fetchSite = String(req.headers['sec-fetch-site'] || '').trim().toLowerCase();
+    if (fetchSite === 'cross-site')
+        return false;
+    const origin = String(req.headers.origin || '').trim();
+    if (!origin)
+        return false;
+    const host = String(req.headers.host || '').trim().toLowerCase();
+    if (!host)
+        return false;
+    try {
+        return new URL(origin).host.toLowerCase() === host;
+    }
+    catch {
+        return false;
+    }
+}
+function isExactApplyRequest(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return false;
+    const record = body;
+    const keys = Object.keys(record).sort();
+    return keys.length === 2
+        && keys[0] === 'operation'
+        && keys[1] === 'target'
+        && record.operation === 'apply-update'
+        && (record.target === 'app' || record.target === 'global-cli');
+}
+function applyResultStatusCode(result) {
+    if (result.success)
+        return 200;
+    if (result.state === 'busy')
+        return 423;
+    if (result.state === 'blocked')
+        return 409;
+    return 500;
+}
+export function registerLocalUpdateRoutes(dependencies) {
+    const { addRoute, context, platform = process.platform, applyUpdate = applyTaskforceUiUpdate, } = dependencies;
+    const getStatus = dependencies.getStatus || createStatusProvider();
+    const unavailableInCloud = context.authConfig?.runtimeMode === 'cloud';
+    addRoute('GET', '/api/taskforce/update/status', async (_req, res) => {
+        if (unavailableInCloud) {
+            writeJson(res, 404, {
+                success: false,
+                code: 'LOCAL_UPDATE_UNAVAILABLE',
+                error: 'Taskforce self-update is available only in local runtime.',
+            });
+            return;
+        }
+        try {
+            const result = buildUiUpdateOverview(await getStatus(), platform);
+            writeJson(res, 200, { success: true, result });
+        }
+        catch {
+            writeJson(res, 500, {
+                success: false,
+                code: 'UPDATE_STATUS_FAILED',
+                error: 'Taskforce could not determine update availability.',
+            });
+        }
+    });
+    addRoute('POST', '/api/taskforce/update/apply', async (req, res) => {
+        if (unavailableInCloud) {
+            writeJson(res, 404, {
+                success: false,
+                code: 'LOCAL_UPDATE_UNAVAILABLE',
+                error: 'Taskforce self-update is available only in local runtime.',
+            });
+            return;
+        }
+        if (!isSameOriginBrowserRequest(req)) {
+            writeJson(res, 403, {
+                success: false,
+                code: 'UPDATE_ORIGIN_REJECTED',
+                error: 'The update request must originate from this Taskforce app.',
+            });
+            return;
+        }
+        const contentType = String(req.headers['content-type'] || '').toLowerCase();
+        if (!contentType.startsWith('application/json')) {
+            writeJson(res, 415, {
+                success: false,
+                code: 'UPDATE_JSON_REQUIRED',
+                error: 'The update request must use application/json.',
+            });
+            return;
+        }
+        let body;
+        try {
+            body = await parseJsonBody(req, 1024);
+        }
+        catch {
+            writeJson(res, 400, {
+                success: false,
+                code: 'UPDATE_REQUEST_INVALID',
+                error: 'The update request is invalid.',
+            });
+            return;
+        }
+        if (!isExactApplyRequest(body)) {
+            writeJson(res, 400, {
+                success: false,
+                code: 'UPDATE_REQUEST_INVALID',
+                error: 'Expected only operation=apply-update and target=app or global-cli.',
+            });
+            return;
+        }
+        try {
+            const result = await applyUpdate(body.target, {
+                getStatus,
+                platform,
+            });
+            writeJson(res, applyResultStatusCode(result), {
+                success: result.success,
+                result,
+            });
+        }
+        catch {
+            writeJson(res, 500, {
+                success: false,
+                code: 'UPDATE_FAILED',
+                error: 'Taskforce could not complete the update.',
+            });
+        }
+    });
+}

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

@@ -1,11 +1,38 @@
 import { IncomingMessage, ServerResponse } from 'http';
 import type { TaskforceAuthConfig } from '../auth.js';
 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';
+export interface LocalServiceRouteContext {
+    generation: string;
+    protocolVersion: string;
+    appVersion: string;
+    ownerPid: number;
+    bootstrapCapability: string;
+    ownershipKey: string;
+    projectIdentity: string;
+    operationClientId: string;
+    sessions: LocalServiceSessionManager;
+    requestShutdown: (mode: 'refuse' | 'drain' | 'force') => void;
+    diagnostics?: () => Record<string, unknown>;
+    endpoint?: () => string | null;
+}
 export type RouteHandler = (req: IncomingMessage, res: ServerResponse, params: Record<string, string>) => Promise<void>;
 export interface RouteContext {
     authConfig?: TaskforceAuthConfig;
     objectStorage?: ResolvedObjectStorageConfig;
+    localSyncCoordinator?: LocalSyncCoordinatorRouteServices | null;
+    workspaceSyncDataServices?: WorkspaceSyncServerDataServices;
+    localService?: LocalServiceRouteContext;
 }
+export declare function resolveHttpErrorStatusCode(error: unknown, fallback?: number): number;
+export declare function formatApiErrorResponse(error: unknown, fallbackStatusCode?: number): {
+    statusCode: number;
+    body: {
+        error: string;
+    };
+};
 export declare function parseJsonBody(req: IncomingMessage, maxBytes?: number): Promise<any>;
 export declare function parseFormBody(req: IncomingMessage, maxBytes?: number): Promise<Record<string, string>>;
 export declare function escapeHtml(value: unknown): string;

package/dist/server/routes/primitives.js

@@ -1,9 +1,27 @@
 const DEFAULT_MAX_JSON_BODY_BYTES = 1024 * 1024; // 1MB
+const DEFAULT_INTERNAL_ERROR_MESSAGE = 'Internal server error.';
 function createHttpError(message, statusCode) {
     const error = new Error(message);
     error.statusCode = statusCode;
     return error;
 }
+export function resolveHttpErrorStatusCode(error, fallback = 500) {
+    const statusCode = Number(error?.statusCode);
+    if (Number.isFinite(statusCode) && statusCode >= 400 && statusCode <= 599) {
+        return Math.floor(statusCode);
+    }
+    return fallback;
+}
+export function formatApiErrorResponse(error, fallbackStatusCode = 500) {
+    const statusCode = resolveHttpErrorStatusCode(error, fallbackStatusCode);
+    if (statusCode >= 500) {
+        return { statusCode, body: { error: DEFAULT_INTERNAL_ERROR_MESSAGE } };
+    }
+    const message = error instanceof Error
+        ? String(error.message || '').trim()
+        : String(error?.message || error || '').trim();
+    return { statusCode, body: { error: message || 'Request failed.' } };
+}
 export async function parseJsonBody(req, maxBytes = DEFAULT_MAX_JSON_BODY_BYTES) {
     const safeMaxBytes = Number.isFinite(maxBytes) && maxBytes > 0
         ? Math.floor(maxBytes)