@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/services/githubReviewEvidenceService.d.ts

@@ -0,0 +1,93 @@
+import type { GitHubReviewEvidenceInstallationBinding } from '../storage/githubReviewEvidenceInstallationStore.js';
+export type GitHubReviewEvidenceErrorCode = 'github_app_not_configured' | 'github_installation_not_bound' | 'github_installation_unavailable' | 'github_installation_revoked' | 'github_permission_denied' | 'github_rate_limited' | 'github_repository_unavailable' | 'github_evidence_mismatch' | 'github_pull_request_not_reviewable' | 'github_request_timed_out';
+export declare class GitHubReviewEvidenceError extends Error {
+    readonly code: GitHubReviewEvidenceErrorCode;
+    readonly statusCode: number;
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, code: GitHubReviewEvidenceErrorCode, statusCode: number, retryAfterSeconds?: number | null);
+}
+export interface GitHubReviewAppConfig {
+    appId: string;
+    privateKey: string;
+}
+export interface GitHubInstallationInspection {
+    installationId: string;
+    accountId: string;
+    accountLogin: string;
+    accountType: string;
+    repositorySelection: string;
+}
+export interface GitHubReviewEvidenceRequest {
+    workspaceId: string;
+    repositoryFullName: string;
+    commitSha: string;
+    pullRequestNumber: number;
+    expectedBaseRef?: string | null;
+    expectedHeadRef?: string | null;
+    integrationBranch?: string | null;
+}
+export interface VerifiedGitHubReviewEvidence {
+    repository: {
+        id: string;
+        fullName: string;
+        private: boolean;
+        defaultBranch: string;
+    };
+    commit: {
+        sha: string;
+    };
+    pullRequest: {
+        number: number;
+        state: string;
+        merged: boolean;
+        mergeCommitSha: string | null;
+        head: {
+            ref: string;
+            sha: string;
+        };
+        base: {
+            ref: string;
+            sha: string;
+        };
+    };
+    integration: {
+        branch: string;
+        comparisonStatus: 'ahead' | 'identical';
+        containsCommit: true;
+    } | null;
+    verifiedAt: string;
+}
+export interface GitHubReviewEvidenceVerifier {
+    verify(request: GitHubReviewEvidenceRequest): Promise<VerifiedGitHubReviewEvidence>;
+}
+interface GitHubReviewEvidenceServiceOptions {
+    config: GitHubReviewAppConfig | null;
+    getBinding: (workspaceId: string) => GitHubReviewEvidenceInstallationBinding | null;
+    fetchImpl?: typeof fetch;
+    apiBaseUrl?: string;
+    timeoutMs?: number;
+    now?: () => Date;
+    audit?: (event: {
+        action: 'github.review-evidence.verify.succeeded' | 'github.review-evidence.verify.failed';
+        workspaceId: string;
+        repositoryFullName: string;
+        commitSha: string;
+        pullRequestNumber: number;
+        code?: GitHubReviewEvidenceErrorCode;
+    }) => void;
+}
+export declare function resolveGitHubReviewAppConfig(env?: NodeJS.ProcessEnv): GitHubReviewAppConfig | null;
+export declare class GitHubReviewEvidenceService implements GitHubReviewEvidenceVerifier {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly apiBaseUrl;
+    private readonly timeoutMs;
+    private readonly now;
+    constructor(options: GitHubReviewEvidenceServiceOptions);
+    private requireConfig;
+    private requestJson;
+    inspectInstallation(installationId: string): Promise<GitHubInstallationInspection>;
+    private mintRepositoryToken;
+    verify(request: GitHubReviewEvidenceRequest): Promise<VerifiedGitHubReviewEvidence>;
+}
+export {};

package/dist/services/githubReviewEvidenceService.js

@@ -0,0 +1,336 @@
+import { sign } from 'crypto';
+const DEFAULT_API_BASE_URL = 'https://api.github.com';
+const API_VERSION = '2026-03-10';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_GITHUB_RESPONSE_BYTES = 2 * 1024 * 1024;
+export class GitHubReviewEvidenceError extends Error {
+    code;
+    statusCode;
+    retryAfterSeconds;
+    constructor(message, code, statusCode, retryAfterSeconds = null) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'GitHubReviewEvidenceError';
+    }
+}
+export function resolveGitHubReviewAppConfig(env = process.env) {
+    const appId = String(env.TASKFORCE_GITHUB_REVIEW_APP_ID || '').trim();
+    const encodedPrivateKey = String(env.TASKFORCE_GITHUB_REVIEW_APP_PRIVATE_KEY_BASE64 || '').trim();
+    const privateKey = encodedPrivateKey ? Buffer.from(encodedPrivateKey, 'base64').toString('utf8') : '';
+    return appId && privateKey ? { appId, privateKey } : null;
+}
+function createAppJwt(config, now) {
+    const issuedAt = Math.floor(now.getTime() / 1_000) - 60;
+    const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({
+        iat: issuedAt,
+        exp: issuedAt + 9 * 60,
+        iss: config.appId,
+    })).toString('base64url');
+    const signingInput = `${header}.${payload}`;
+    try {
+        const signature = sign('RSA-SHA256', Buffer.from(signingInput), config.privateKey).toString('base64url');
+        return `${signingInput}.${signature}`;
+    }
+    catch {
+        throw new GitHubReviewEvidenceError('GitHub review verification is not configured correctly.', 'github_app_not_configured', 503);
+    }
+}
+function requiredString(value, label, maxLength = 255) {
+    const normalized = String(value || '').trim();
+    if (!normalized || normalized.length > maxLength || /[\u0000-\u001f\u007f]/.test(normalized)) {
+        throw new GitHubReviewEvidenceError(`${label} is invalid.`, 'github_evidence_mismatch', 400);
+    }
+    return normalized;
+}
+function normalizeRepositoryFullName(value) {
+    const fullName = requiredString(value, 'repositoryFullName', 201);
+    const parts = fullName.split('/');
+    if (parts.length !== 2 || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(parts[0]) || !/^[A-Za-z0-9._-]{1,100}$/.test(parts[1])) {
+        throw new GitHubReviewEvidenceError('repositoryFullName is invalid.', 'github_evidence_mismatch', 400);
+    }
+    return { owner: parts[0], name: parts[1], fullName };
+}
+function normalizeSha(value) {
+    const sha = String(value || '').trim().toLowerCase();
+    if (!/^[0-9a-f]{40}$/.test(sha)) {
+        throw new GitHubReviewEvidenceError('commitSha must be a full 40-character SHA.', 'github_evidence_mismatch', 400);
+    }
+    return sha;
+}
+function retryAfterSeconds(response) {
+    const raw = Number(response.headers.get('retry-after'));
+    if (Number.isFinite(raw) && raw > 0)
+        return Math.ceil(raw);
+    const reset = Number(response.headers.get('x-ratelimit-reset'));
+    if (Number.isFinite(reset) && reset > 0)
+        return Math.max(1, Math.ceil(reset - Date.now() / 1_000));
+    return null;
+}
+function mapGitHubHttpError(response, installationRequest) {
+    if (response.status === 401) {
+        return new GitHubReviewEvidenceError('The GitHub App installation is no longer authorized.', 'github_installation_revoked', 503);
+    }
+    if (response.status === 429
+        || (response.status === 403 && (response.headers.get('x-ratelimit-remaining') === '0'
+            || response.headers.has('retry-after')))) {
+        return new GitHubReviewEvidenceError('GitHub verification is temporarily rate limited.', 'github_rate_limited', 503, retryAfterSeconds(response));
+    }
+    if (response.status === 403) {
+        return new GitHubReviewEvidenceError('The GitHub App installation lacks a required read permission.', 'github_permission_denied', 503);
+    }
+    if (response.status === 404) {
+        if (installationRequest) {
+            return new GitHubReviewEvidenceError('The GitHub App installation is no longer authorized.', 'github_installation_revoked', 503);
+        }
+        return new GitHubReviewEvidenceError('The repository or evidence is unavailable to this GitHub App installation.', 'github_repository_unavailable', 422);
+    }
+    if (response.status === 422) {
+        return new GitHubReviewEvidenceError('The repository or evidence is unavailable to this GitHub App installation.', 'github_repository_unavailable', 422);
+    }
+    return new GitHubReviewEvidenceError('GitHub verification is temporarily unavailable.', 'github_installation_unavailable', 503);
+}
+async function readBoundedJson(response) {
+    const contentLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > MAX_GITHUB_RESPONSE_BYTES) {
+        throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+    }
+    if (!response.body) {
+        throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            size += value.byteLength;
+            if (size > MAX_GITHUB_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+            }
+            chunks.push(value);
+        }
+        const body = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString('utf8');
+        return JSON.parse(body);
+    }
+    catch (error) {
+        if (error instanceof GitHubReviewEvidenceError)
+            throw error;
+        throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export class GitHubReviewEvidenceService {
+    options;
+    fetchImpl;
+    apiBaseUrl;
+    timeoutMs;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl || fetch;
+        this.apiBaseUrl = String(options.apiBaseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.now = options.now || (() => new Date());
+    }
+    requireConfig() {
+        if (!this.options.config) {
+            throw new GitHubReviewEvidenceError('GitHub review verification is not configured.', 'github_app_not_configured', 503);
+        }
+        return this.options.config;
+    }
+    async requestJson(path, init, installationRequest = false) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchImpl(`${this.apiBaseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+                headers: {
+                    Accept: 'application/vnd.github+json',
+                    'X-GitHub-Api-Version': API_VERSION,
+                    'User-Agent': 'taskforce-review-evidence',
+                    ...(init.headers || {}),
+                },
+            });
+            if (!response.ok)
+                throw mapGitHubHttpError(response, installationRequest);
+            return await readBoundedJson(response);
+        }
+        catch (error) {
+            if (error instanceof GitHubReviewEvidenceError)
+                throw error;
+            if (error?.name === 'AbortError') {
+                throw new GitHubReviewEvidenceError('GitHub verification timed out.', 'github_request_timed_out', 503);
+            }
+            throw new GitHubReviewEvidenceError('GitHub verification is temporarily unavailable.', 'github_installation_unavailable', 503);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async inspectInstallation(installationId) {
+        const config = this.requireConfig();
+        const normalizedInstallationId = String(installationId || '').trim();
+        if (!/^\d+$/.test(normalizedInstallationId)) {
+            throw new GitHubReviewEvidenceError('installationId must be a numeric GitHub installation ID.', 'github_evidence_mismatch', 400);
+        }
+        const response = await this.requestJson(`/app/installations/${normalizedInstallationId}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${createAppJwt(config, this.now())}` },
+        }, true);
+        if (response.suspended_at) {
+            throw new GitHubReviewEvidenceError('The GitHub App installation is suspended.', 'github_installation_revoked', 503);
+        }
+        const permissions = response.permissions || {};
+        if (permissions.contents !== 'read' || permissions.pull_requests !== 'read' || permissions.metadata !== 'read') {
+            throw new GitHubReviewEvidenceError('The GitHub App installation lacks required read permissions.', 'github_permission_denied', 503);
+        }
+        const accountId = String(response.account?.id || '').trim();
+        const accountLogin = String(response.account?.login || '').trim();
+        if (!accountId || !accountLogin) {
+            throw new GitHubReviewEvidenceError('The GitHub App installation metadata is incomplete.', 'github_installation_unavailable', 503);
+        }
+        return {
+            installationId: String(response.id || normalizedInstallationId),
+            accountId,
+            accountLogin,
+            accountType: String(response.account?.type || 'unknown'),
+            repositorySelection: String(response.repository_selection || 'selected'),
+        };
+    }
+    async mintRepositoryToken(binding, repositoryName) {
+        const config = this.requireConfig();
+        const response = await this.requestJson(`/app/installations/${binding.installationId}/access_tokens`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${createAppJwt(config, this.now())}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                repositories: [repositoryName],
+                permissions: { metadata: 'read', contents: 'read', pull_requests: 'read' },
+            }),
+        }, true);
+        const token = String(response.token || '').trim();
+        if (!token) {
+            throw new GitHubReviewEvidenceError('GitHub did not issue an installation token.', 'github_installation_unavailable', 503);
+        }
+        return token;
+    }
+    async verify(request) {
+        const workspaceId = requiredString(request.workspaceId, 'workspaceId');
+        const repository = normalizeRepositoryFullName(request.repositoryFullName);
+        const commitSha = normalizeSha(request.commitSha);
+        const pullRequestNumber = Number(request.pullRequestNumber);
+        if (!Number.isSafeInteger(pullRequestNumber) || pullRequestNumber < 1) {
+            throw new GitHubReviewEvidenceError('pullRequestNumber must be a positive integer.', 'github_evidence_mismatch', 400);
+        }
+        try {
+            const binding = this.options.getBinding(workspaceId);
+            if (!binding) {
+                throw new GitHubReviewEvidenceError('This workspace has no GitHub App installation binding.', 'github_installation_not_bound', 409);
+            }
+            const token = await this.mintRepositoryToken(binding, repository.name);
+            const authorization = { Authorization: `Bearer ${token}` };
+            const repoPath = `/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.name)}`;
+            const [repo, commit, pullRequest] = await Promise.all([
+                this.requestJson(repoPath, { method: 'GET', headers: authorization }),
+                this.requestJson(`${repoPath}/commits/${commitSha}`, { method: 'GET', headers: authorization }),
+                this.requestJson(`${repoPath}/pulls/${pullRequestNumber}`, { method: 'GET', headers: authorization }),
+            ]);
+            const actualRepo = String(repo.full_name || '').trim();
+            const actualCommitSha = String(commit.sha || '').trim().toLowerCase();
+            const headSha = String(pullRequest.head?.sha || '').trim().toLowerCase();
+            const headRef = String(pullRequest.head?.ref || '').trim();
+            const baseRef = String(pullRequest.base?.ref || '').trim();
+            const baseSha = String(pullRequest.base?.sha || '').trim().toLowerCase();
+            const headRepo = String(pullRequest.head?.repo?.full_name || '').trim();
+            const baseRepo = String(pullRequest.base?.repo?.full_name || '').trim();
+            if (actualRepo.toLowerCase() !== repository.fullName.toLowerCase()
+                || actualCommitSha !== commitSha
+                || Number(pullRequest.number) !== pullRequestNumber
+                || headSha !== commitSha
+                || headRepo.toLowerCase() !== repository.fullName.toLowerCase()
+                || baseRepo.toLowerCase() !== repository.fullName.toLowerCase()
+                || !/^[0-9a-f]{40}$/.test(baseSha)) {
+                throw new GitHubReviewEvidenceError('GitHub repository, commit, or pull-request evidence does not match the requested immutable identity.', 'github_evidence_mismatch', 422);
+            }
+            if (request.expectedHeadRef && headRef !== requiredString(request.expectedHeadRef, 'expectedHeadRef')) {
+                throw new GitHubReviewEvidenceError('The pull-request head branch does not match the expected branch.', 'github_evidence_mismatch', 422);
+            }
+            if (request.expectedBaseRef && baseRef !== requiredString(request.expectedBaseRef, 'expectedBaseRef')) {
+                throw new GitHubReviewEvidenceError('The pull-request base branch does not match the expected branch.', 'github_evidence_mismatch', 422);
+            }
+            const state = String(pullRequest.state || '').trim().toLowerCase();
+            const merged = pullRequest.merged === true;
+            if (state === 'closed' && !merged) {
+                throw new GitHubReviewEvidenceError('A closed, unmerged pull request is not valid review evidence.', 'github_pull_request_not_reviewable', 422);
+            }
+            let integration = null;
+            if (request.integrationBranch) {
+                const branch = requiredString(request.integrationBranch, 'integrationBranch');
+                const comparison = await this.requestJson(`${repoPath}/compare/${commitSha}...${encodeURIComponent(branch)}`, { method: 'GET', headers: authorization });
+                const comparisonStatus = String(comparison.status || '').trim().toLowerCase();
+                if (comparisonStatus !== 'ahead' && comparisonStatus !== 'identical') {
+                    throw new GitHubReviewEvidenceError('The requested commit is not reachable from the integration branch.', 'github_evidence_mismatch', 422);
+                }
+                integration = {
+                    branch,
+                    comparisonStatus,
+                    containsCommit: true,
+                };
+            }
+            const result = {
+                repository: {
+                    id: String(repo.id || ''),
+                    fullName: actualRepo,
+                    private: repo.private === true,
+                    defaultBranch: String(repo.default_branch || ''),
+                },
+                commit: { sha: actualCommitSha },
+                pullRequest: {
+                    number: Number(pullRequest.number || pullRequestNumber),
+                    state,
+                    merged,
+                    mergeCommitSha: pullRequest.merge_commit_sha ? String(pullRequest.merge_commit_sha).toLowerCase() : null,
+                    head: { ref: headRef, sha: headSha },
+                    base: { ref: baseRef, sha: baseSha },
+                },
+                integration,
+                verifiedAt: this.now().toISOString(),
+            };
+            this.options.audit?.({
+                action: 'github.review-evidence.verify.succeeded',
+                workspaceId,
+                repositoryFullName: repository.fullName,
+                commitSha,
+                pullRequestNumber,
+            });
+            return result;
+        }
+        catch (error) {
+            const normalized = error instanceof GitHubReviewEvidenceError
+                ? error
+                : new GitHubReviewEvidenceError('GitHub verification is temporarily unavailable.', 'github_installation_unavailable', 503);
+            this.options.audit?.({
+                action: 'github.review-evidence.verify.failed',
+                workspaceId,
+                repositoryFullName: repository.fullName,
+                commitSha,
+                pullRequestNumber,
+                code: normalized.code,
+            });
+            throw normalized;
+        }
+    }
+}

package/dist/services/modelGateway.d.ts

@@ -11,6 +11,7 @@ export interface ModelGatewaySelection {
     actorUserId?: string | null;
     connectionScope?: TaskforceAgentConnectionScope;
     connectionId?: string | null;
+    connectionOwnerUserId?: string | null;
 }
 export interface ModelProviderCredentialResolution {
     source: TaskforceAgentModelSource;
@@ -76,6 +77,12 @@ export interface ModelGatewayGenerateResult {
     stopReason?: string;
     usage?: ModelGatewayUsage;
     latencyMs?: number;
+    sourceMetadata?: {
+        modelSource: TaskforceAgentModelSource;
+        connectionScope?: TaskforceAgentConnectionScope;
+        providerKey: string;
+        billable: boolean;
+    };
 }
 export interface ModelGateway {
     generate(input: ModelGatewayGenerateInput): Promise<ModelGatewayGenerateResult>;

package/dist/services/modelProviderConnectionService.d.ts

@@ -0,0 +1,71 @@
+import type { ModelProviderConnectionDisplayMetadata, ModelProviderConnectionRecord, ModelProviderConnectionLease, ModelProviderConnectionStore } from '../storage/modelProviderConnectionStore.js';
+import type { ModelProviderCredentialHomeManager } from './modelProviderCredentialHome.js';
+export interface PublicModelProviderConnection {
+    id: string;
+    providerKey: string;
+    authenticationType: string;
+    lifecycleStatus: ModelProviderConnectionRecord['lifecycleStatus'];
+    displayMetadata: ModelProviderConnectionDisplayMetadata;
+    lastVerifiedAt: string | null;
+    lastRefreshedAt: string | null;
+    failureCode: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ModelProviderConnectionOperationContext {
+    connection: ModelProviderConnectionRecord;
+    environment: NodeJS.ProcessEnv;
+    lease: ModelProviderConnectionLease;
+    signal: AbortSignal;
+}
+export type ModelProviderConnectionOperation = (context: ModelProviderConnectionOperationContext) => Promise<{
+    displayMetadata?: unknown;
+} | void>;
+export interface ModelProviderConnectionLifecycleHandlers {
+    verify?: ModelProviderConnectionOperation;
+    refresh?: ModelProviderConnectionOperation;
+    disconnect?: ModelProviderConnectionOperation;
+}
+export declare class ModelProviderConnectionService {
+    private readonly store;
+    private readonly credentialHomes;
+    private readonly hasGrant;
+    private readonly supportedConnectionTypes;
+    private readonly handlers;
+    constructor(store: ModelProviderConnectionStore, credentialHomes: ModelProviderCredentialHomeManager, hasGrant: (userId: string) => boolean, handlers?: Array<{
+        providerKey: string;
+        authenticationType: string;
+        lifecycle: ModelProviderConnectionLifecycleHandlers;
+    }>, supportedConnectionTypes?: Array<{
+        providerKey: string;
+        authenticationType: string;
+    }>);
+    create(input: {
+        ownerUserId: string;
+        providerKey: string;
+        authenticationType: string;
+    }): PublicModelProviderConnection;
+    list(ownerUserId: string): PublicModelProviderConnection[];
+    get(ownerUserId: string, connectionId: string): PublicModelProviderConnection;
+    rename(ownerUserId: string, connectionId: string, displayName: unknown): PublicModelProviderConnection;
+    verify(ownerUserId: string, connectionId: string): Promise<PublicModelProviderConnection>;
+    refresh(ownerUserId: string, connectionId: string): Promise<PublicModelProviderConnection>;
+    disconnect(ownerUserId: string, connectionId: string): Promise<PublicModelProviderConnection>;
+    cleanup(ownerUserId: string, connectionId: string): Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    withConnectionLease<T>(input: {
+        ownerUserId: string;
+        connectionId: string;
+        operation: 'login' | 'verify' | 'refresh' | 'invoke' | 'disconnect';
+        requireGrant?: boolean;
+        leaseDurationMs?: number;
+    }, callback: (context: ModelProviderConnectionOperationContext) => Promise<T>): Promise<T>;
+    assertReady(ownerUserId: string, connectionId: string): ModelProviderConnectionRecord;
+    private runWithConnectionLease;
+    private runOperation;
+    private assertGranted;
+    private assertOperationAvailable;
+    private assertOwner;
+}