@withtruing/companion 0.0.0-stage → 0.13.1

package/dist/design-context.js

@@ -0,0 +1,54 @@
+/**
+ * findDesignFiles is copied VERBATIM from server/design-context.ts, per the companion plan's
+ * own Section 2 item 5: "findDesignFiles(paths: string[]): string[] has zero GitHub-specific
+ * code — copy it verbatim into the companion package (genuinely shared pure logic)." Keep the
+ * two copies in sync by hand if the pattern list ever changes.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { listRepoFiles } from './local-scan.js';
+const CONFIG_NAMES = ['tailwind.config.js', 'tailwind.config.ts', 'tailwind.config.mjs', 'tailwind.config.cjs'];
+const TOKEN_NAMES = ['theme.css', 'tokens.css', 'design-tokens.css', 'design-tokens.json'];
+const GUIDELINES_NAMES = ['guidelines.md', 'design-guidelines.md', 'style-guide.md'];
+const COMPONENT_DIR_HINTS = ['components/ui/', 'app/components/', 'src/components/', 'src/ui/'];
+const MAX_FILES = 8;
+function basename(path) {
+    return path.split('/').pop() ?? path;
+}
+/** Given the repo's full list of blob paths, pick candidate design-signal files. */
+export function findDesignFiles(paths) {
+    const named = paths.filter((p) => {
+        const b = basename(p).toLowerCase();
+        return CONFIG_NAMES.includes(b) || TOKEN_NAMES.includes(b) || GUIDELINES_NAMES.includes(b);
+    });
+    const componentFiles = paths
+        .filter((p) => COMPONENT_DIR_HINTS.some((hint) => p.toLowerCase().includes(hint)))
+        .filter((p) => /\.(tsx|jsx|css)$/.test(p))
+        .sort((a, b) => a.length - b.length)
+        .slice(0, MAX_FILES - named.length);
+    return [...named, ...componentFiles].slice(0, MAX_FILES);
+}
+/** The local-read counterpart to server/design-context.ts's buildDesignContext — same
+ *  findDesignFiles selection, but reading the local checkout with no MAX_CHARS_PER_FILE-style
+ *  truncation (the server's own cap exists only because a GitHub file read is a metered,
+ *  rate-limited network call; a local read isn't). Empty string if nothing found — the caller
+ *  (api-key-caller.ts's runDesignPromptTask) treats that as "propose a visual language from
+ *  scratch instead", same fallback server/index.ts's route already uses today. */
+export async function buildLocalDesignContext(repoPath) {
+    const paths = await listRepoFiles(repoPath);
+    const files = findDesignFiles(paths);
+    if (!files.length)
+        return '';
+    const sections = [];
+    for (const path of files) {
+        let text;
+        try {
+            text = await readFile(join(repoPath, path), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        sections.push(`### ${path}\n\`\`\`\n${text}\n\`\`\``);
+    }
+    return sections.join('\n\n');
+}

package/dist/git-range.js

@@ -0,0 +1,291 @@
+import { randomUUID } from 'node:crypto';
+import spawn from 'cross-spawn';
+import { detectSchemaImpact, validSchemaProbe, } from './schema-entities.js';
+import { managedFetchEnvironment, networkGitEnvironment, reportBackgroundFetch } from './managed-repo.js';
+export const GIT_RANGE_MAX_HTTP_BYTES = 1_572_864;
+export const GIT_RANGE_MAX_COMMITS = 1_000;
+export const GIT_RANGE_MAX_PATHS = 3_000;
+export const GIT_RANGE_COMMAND_TIMEOUT_MS = 60_000;
+export const GIT_RANGE_METADATA_OUTPUT_BYTES = 1_048_576;
+export const GIT_RANGE_ENUMERATION_OUTPUT_BYTES = 16_777_216;
+export const GIT_RANGE_OBJECT_OUTPUT_BYTES = 25_165_824;
+export const GIT_RANGE_PATH_OUTPUT_BYTES = 16_777_216;
+const SHA = /^[0-9a-f]{40}$/;
+const TASK_ID = /^[0-9a-f-]{36}$/;
+const decoder = new TextDecoder('utf-8', { fatal: true });
+class GitCommandFailure extends Error {
+    kind;
+    exitCode;
+    constructor(kind, exitCode = null) {
+        super(kind);
+        this.kind = kind;
+        this.exitCode = exitCode;
+    }
+}
+const GIT_RANGE_CAPTURED_STDERR_BYTES = 8_192;
+export function gitRangeEnvironment(parent = process.env) {
+    const environment = networkGitEnvironment(parent);
+    delete environment.GIT_CONFIG_NOSYSTEM;
+    return environment;
+}
+function runGit(repoPath, args, outputLimit, input, environment) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['--no-replace-objects', ...args], {
+            cwd: repoPath,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: environment ?? gitRangeEnvironment(),
+            windowsHide: true,
+        });
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const overflow = () => {
+            child.kill('SIGKILL');
+            finish(new GitCommandFailure('resource'));
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes + stderrBytes > outputLimit)
+                return overflow();
+            stdout.push(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (stderrBytes < GIT_RANGE_CAPTURED_STDERR_BYTES)
+                stderr.push(chunk.subarray(0, GIT_RANGE_CAPTURED_STDERR_BYTES - stderrBytes));
+            stderrBytes += chunk.length;
+            if (stdoutBytes + stderrBytes > outputLimit)
+                overflow();
+        });
+        child.on('error', () => finish(new GitCommandFailure('resource')));
+        child.on('close', (code, signal) => {
+            if (signal || code === null)
+                return finish(new GitCommandFailure('resource'));
+            finish(undefined, { stdout: Buffer.concat(stdout), exitCode: code, stderr: Buffer.concat(stderr).toString('utf8') });
+        });
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish(new GitCommandFailure('resource'));
+        }, GIT_RANGE_COMMAND_TIMEOUT_MS);
+        if (input)
+            child.stdin?.end(input);
+        else
+            child.stdin?.end();
+    });
+}
+function strictText(bytes) {
+    try {
+        return decoder.decode(bytes);
+    }
+    catch {
+        throw new GitCommandFailure('resource');
+    }
+}
+function exactLine(bytes) {
+    const text = strictText(bytes);
+    if (!text.endsWith('\n') || text.endsWith('\n\n') || text.includes('\r'))
+        throw new GitCommandFailure('resource');
+    return text.slice(0, -1);
+}
+function truncateUtf16(value, limit) {
+    if (value.length <= limit)
+        return value;
+    let end = limit;
+    const last = value.charCodeAt(end - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        end--;
+    return value.slice(0, end);
+}
+function parseCommitObjects(bytes, requested) {
+    const commits = [];
+    let offset = 0;
+    for (const expected of requested) {
+        const headerEnd = bytes.indexOf(0x0a, offset);
+        if (headerEnd === -1)
+            throw new GitCommandFailure('resource');
+        const header = strictText(bytes.subarray(offset, headerEnd));
+        const match = /^([0-9a-f]{40}) commit ([0-9]+)$/.exec(header);
+        if (!match || match[1] !== expected)
+            throw new GitCommandFailure('resource');
+        const size = Number(match[2]);
+        if (!Number.isSafeInteger(size) || size < 0 || headerEnd + 1 + size >= bytes.length)
+            throw new GitCommandFailure('resource');
+        const object = bytes.subarray(headerEnd + 1, headerEnd + 1 + size);
+        if (bytes[headerEnd + 1 + size] !== 0x0a)
+            throw new GitCommandFailure('resource');
+        offset = headerEnd + 1 + size + 1;
+        const boundary = object.indexOf(Buffer.from('\n\n'));
+        if (boundary === -1)
+            throw new GitCommandFailure('resource');
+        const message = strictText(object.subarray(boundary + 2));
+        const [first = '', ...rest] = message.split('\n');
+        commits.push({
+            sha: expected,
+            title: truncateUtf16(first.trim(), 500),
+            message: truncateUtf16(rest.join('\n').trim(), 20_000),
+        });
+    }
+    if (offset !== bytes.length)
+        throw new GitCommandFailure('resource');
+    return commits;
+}
+export function parseNameStatus(bytes) {
+    if (bytes.length === 0)
+        return { changedPaths: [], truncatedFiles: false };
+    if (bytes[bytes.length - 1] !== 0)
+        throw new GitCommandFailure('resource');
+    const fields = bytes.subarray(0, -1).toString('binary').split('\0').map((field) => Buffer.from(field, 'binary'));
+    const paths = new Set();
+    for (let index = 0; index < fields.length;) {
+        const status = strictText(fields[index++]);
+        const scored = /^([RC])([0-9]{1,3})$/.exec(status);
+        const twoPaths = !!scored && Number(scored[2]) <= 100;
+        if ((!twoPaths && scored) || (!twoPaths && !/^[ACDMRTUXB]$/.test(status)))
+            throw new GitCommandFailure('resource');
+        const required = twoPaths ? 2 : 1;
+        if (index + required > fields.length)
+            throw new GitCommandFailure('resource');
+        for (let count = 0; count < required; count++)
+            paths.add(strictText(fields[index++]));
+    }
+    const all = [...paths].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    return { changedPaths: all.slice(0, GIT_RANGE_MAX_PATHS), truncatedFiles: all.length > GIT_RANGE_MAX_PATHS };
+}
+export function fitsGitRangeTransport(result) {
+    return Buffer.byteLength(JSON.stringify({ result, filesRead: [] }), 'utf8') <= GIT_RANGE_MAX_HTTP_BYTES;
+}
+const failure = (code) => ({ ok: false, code });
+export async function runGitRangeTask(task, repoPath, connection) {
+    const payload = task.payload;
+    const branch = payload.branch;
+    const base = payload.base;
+    const remote = connection.remote ?? 'origin';
+    let destination = null;
+    try {
+        if (task.maxBudgetUsd !== 0 || !TASK_ID.test(task.id) || typeof branch !== 'string'
+            || !(base === null || (typeof base === 'string' && SHA.test(base))) || typeof remote !== 'string' || !remote
+            || (payload.schemaProbe !== undefined && !validSchemaProbe(payload.schemaProbe))) {
+            return { result: failure('history_failed'), filesRead: [] };
+        }
+        const branchCheck = await runGit(repoPath, ['check-ref-format', '--branch', branch], GIT_RANGE_METADATA_OUTPUT_BYTES);
+        const remoteList = await runGit(repoPath, ['remote'], GIT_RANGE_METADATA_OUTPUT_BYTES);
+        if (branchCheck.exitCode !== 0)
+            return { result: failure('branch_missing'), filesRead: [] };
+        const remotes = exactLine(Buffer.concat([remoteList.stdout, remoteList.stdout.length === 0 ? Buffer.from('\n') : Buffer.alloc(0)]));
+        if (remoteList.exitCode !== 0 || !remotes.split('\n').includes(remote))
+            return { result: failure('branch_missing'), filesRead: [] };
+        destination = `refs/product-console/git-range/${task.id}/${randomUUID()}/head`;
+        const destinationCheck = await runGit(repoPath, ['check-ref-format', destination], GIT_RANGE_METADATA_OUTPUT_BYTES);
+        const sourceCheck = await runGit(repoPath, ['check-ref-format', `refs/heads/${branch}`], GIT_RANGE_METADATA_OUTPUT_BYTES);
+        if (destinationCheck.exitCode !== 0 || sourceCheck.exitCode !== 0)
+            return { result: failure('branch_missing'), filesRead: [] };
+        const fetchEnvironment = await managedFetchEnvironment(repoPath);
+        delete fetchEnvironment.GIT_CONFIG_NOSYSTEM;
+        const fetched = await runGit(repoPath, [
+            'fetch', '--no-tags', '--refmap=', '--no-write-fetch-head', '--no-recurse-submodules', '--',
+            remote, `+refs/heads/${branch}:${destination}`,
+        ], GIT_RANGE_METADATA_OUTPUT_BYTES, undefined, fetchEnvironment);
+        reportBackgroundFetch(repoPath, { ok: fetched.exitCode === 0, stderr: fetched.stderr });
+        if (fetched.exitCode !== 0)
+            return { result: failure('fetch_failed'), filesRead: [] };
+        const resolved = await runGit(repoPath, ['rev-parse', '--verify', `${destination}^{commit}`], GIT_RANGE_METADATA_OUTPUT_BYTES);
+        if (resolved.exitCode !== 0)
+            return { result: failure('history_failed'), filesRead: [] };
+        const head = exactLine(resolved.stdout);
+        if (!SHA.test(head))
+            return { result: failure('history_failed'), filesRead: [] };
+        const shallowOutput = await runGit(repoPath, ['rev-parse', '--is-shallow-repository'], GIT_RANGE_METADATA_OUTPUT_BYTES);
+        if (shallowOutput.exitCode !== 0)
+            return { result: failure('history_failed'), filesRead: [] };
+        const shallowText = exactLine(shallowOutput.stdout);
+        if (shallowText !== 'true' && shallowText !== 'false')
+            return { result: failure('history_failed'), filesRead: [] };
+        const historyShallow = shallowText === 'true';
+        if (base === null) {
+            const result = { ok: true, mode: 'head_only', head, base, commits: [], changedPaths: [], totalCommits: null, baseUnavailable: false, truncatedFiles: false, historyShallow };
+            return { result: fitsGitRangeTransport(result) ? result : failure('history_failed'), filesRead: [] };
+        }
+        if (base === head) {
+            const result = { ok: true, mode: 'range', head, base, commits: [], changedPaths: [], totalCommits: 0, baseUnavailable: false, truncatedFiles: false, historyShallow };
+            return { result: fitsGitRangeTransport(result) ? result : failure('history_failed'), filesRead: [] };
+        }
+        const baseCheck = await runGit(repoPath, ['cat-file', '--batch-check'], GIT_RANGE_METADATA_OUTPUT_BYTES, Buffer.from(`${base}\n`));
+        if (baseCheck.exitCode !== 0)
+            return { result: failure('history_failed'), filesRead: [] };
+        const baseDescription = exactLine(baseCheck.stdout);
+        if (baseDescription === `${base} missing`) {
+            return { result: { ok: true, mode: 'base_unavailable', head, base, commits: [], changedPaths: [], totalCommits: null, baseUnavailable: true, baseUnavailableReason: 'object_missing', truncatedFiles: false, historyShallow }, filesRead: [] };
+        }
+        if (!new RegExp(`^${base} commit [0-9]+$`).test(baseDescription))
+            return { result: failure('history_failed'), filesRead: [] };
+        if (historyShallow) {
+            return { result: { ok: true, mode: 'base_unavailable', head, base, commits: [], changedPaths: [], totalCommits: null, baseUnavailable: true, baseUnavailableReason: 'shallow_history', truncatedFiles: false, historyShallow }, filesRead: [] };
+        }
+        const ancestor = await runGit(repoPath, ['merge-base', '--is-ancestor', base, head], GIT_RANGE_METADATA_OUTPUT_BYTES);
+        if (ancestor.exitCode === 1) {
+            return { result: { ok: true, mode: 'base_unavailable', head, base, commits: [], changedPaths: [], totalCommits: null, baseUnavailable: true, baseUnavailableReason: 'not_ancestor', truncatedFiles: false, historyShallow }, filesRead: [] };
+        }
+        if (ancestor.exitCode !== 0)
+            return { result: failure('history_failed'), filesRead: [] };
+        const [enumerated, counted, diff] = await Promise.all([
+            runGit(repoPath, ['rev-list', '--topo-order', '--reverse', `${base}..${head}`, '--'], GIT_RANGE_ENUMERATION_OUTPUT_BYTES),
+            runGit(repoPath, ['rev-list', '--count', `${base}..${head}`, '--'], GIT_RANGE_METADATA_OUTPUT_BYTES),
+            runGit(repoPath, ['diff', '--no-color', '--name-status', '-z', '-M', base, head], GIT_RANGE_PATH_OUTPUT_BYTES),
+        ]);
+        if (enumerated.exitCode !== 0 || counted.exitCode !== 0 || diff.exitCode !== 0)
+            return { result: failure('history_failed'), filesRead: [] };
+        const totalText = exactLine(counted.stdout);
+        if (!/^(0|[1-9][0-9]*)$/.test(totalText))
+            return { result: failure('history_failed'), filesRead: [] };
+        const totalCommits = Number(totalText);
+        if (!Number.isSafeInteger(totalCommits) || totalCommits <= 0)
+            return { result: failure('history_failed'), filesRead: [] };
+        const oidText = strictText(enumerated.stdout);
+        if (!oidText.endsWith('\n'))
+            return { result: failure('history_failed'), filesRead: [] };
+        const oids = oidText.slice(0, -1).split('\n');
+        if (oids.length !== totalCommits || new Set(oids).size !== oids.length || oids.some((oid) => !SHA.test(oid))) {
+            return { result: failure('history_failed'), filesRead: [] };
+        }
+        const selected = oids.slice(0, GIT_RANGE_MAX_COMMITS);
+        const objects = await runGit(repoPath, ['cat-file', '--batch'], GIT_RANGE_OBJECT_OUTPUT_BYTES, Buffer.from(`${selected.join('\n')}\n`));
+        if (objects.exitCode !== 0)
+            return { result: failure('history_failed'), filesRead: [] };
+        const commits = parseCommitObjects(objects.stdout, selected);
+        const paths = parseNameStatus(diff.stdout);
+        const schemaImpact = payload.schemaProbe === undefined
+            ? undefined
+            : await detectSchemaImpact({
+                repoPath,
+                base,
+                head,
+                changedPaths: paths.changedPaths,
+                probe: payload.schemaProbe,
+            });
+        const result = {
+            ok: true, mode: 'range', head, base, commits, changedPaths: paths.changedPaths,
+            totalCommits, baseUnavailable: false, truncatedFiles: paths.truncatedFiles, historyShallow,
+            ...(schemaImpact ? { schemaImpact } : {}),
+        };
+        return { result: fitsGitRangeTransport(result) ? result : failure('history_failed'), filesRead: [] };
+    }
+    catch {
+        return { result: failure('history_failed'), filesRead: [] };
+    }
+    finally {
+        if (destination) {
+            await runGit(repoPath, ['update-ref', '-d', destination], GIT_RANGE_METADATA_OUTPUT_BYTES).catch(() => undefined);
+        }
+    }
+}

package/dist/http-client.js

@@ -0,0 +1,214 @@
+/** Thin wrapper over the requireCompanionAuth-gated routes in server/index.ts. Uses global
+ * fetch (Node 20+, no dependency needed) — see package.json's engines field. */
+import { readFileSync } from 'node:fs';
+import { manifestHash } from './surface-mapper.js';
+const WHOAMI_TIMEOUT_MS = 15_000;
+const CLAIM_TIMEOUT_MS = 10_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+const RESULT_TIMEOUT_MS = 60_000;
+const ERROR_REPORT_TIMEOUT_MS = 30_000;
+const PAIRING_TIMEOUT_MS = 15_000;
+const READINESS_TIMEOUT_MS = 10_000;
+const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+if (typeof packageVersion !== 'string' || !packageVersion) {
+    throw new Error('companion/package.json does not contain a version');
+}
+export const COMPANION_VERSION = packageVersion;
+export const COMPANION_CAPABILITIES = [
+    'auto-surface-map@1',
+    'auto-surface-mapper@1',
+    'auto-surface-mapper@2',
+    'snapshot-read@1',
+    'local-git-range@1',
+    'schema-entities@1',
+    'verify-automatic-surface@1',
+    'map-module-expansion@1',
+];
+const capabilityHeaders = () => ({
+    'X-Companion-Capabilities': COMPANION_CAPABILITIES.join(','),
+});
+export class CompanionHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export const PAIRING_ERROR_MESSAGES = {
+    registration_failed: 'Could not register this repository with the console.',
+    connection_ambiguous: 'More than one connection matches this repository. Remove the duplicate connection and try again.',
+    branch_conflict: 'This repository is already connected with a different default branch.',
+    connection_limit: 'This workspace already has the maximum of 20 connected repositories.',
+    pairing_outcome_failed: 'Setup completion could not be confirmed. Retry this command or return to the console.',
+};
+export class PairingHttpError extends Error {
+    code;
+    constructor(code) {
+        super(PAIRING_ERROR_MESSAGES[code]);
+        this.code = code;
+        this.name = 'PairingHttpError';
+    }
+}
+export class CompanionClient {
+    url;
+    token;
+    constructor(url, token) {
+        this.url = url;
+        this.token = token;
+    }
+    request(path, timeoutMs, init) {
+        return fetch(`${this.url}${path}`, {
+            ...init,
+            headers: {
+                ...init?.headers,
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    async readResponse(response) {
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            throw new CompanionHttpError(response.status, typeof body.error === 'string'
+                ? body.error
+                : `${response.status} ${response.statusText}`);
+        }
+        return body;
+    }
+    async call(path, timeoutMs, init) {
+        return this.readResponse(await this.request(path, timeoutMs, init));
+    }
+    whoami() {
+        return this.call('/api/companion/whoami', WHOAMI_TIMEOUT_MS);
+    }
+    async githubToken(repo) {
+        try {
+            const response = await this.call('/api/companion/github-token', CLAIM_TIMEOUT_MS, { method: 'POST', body: JSON.stringify({ repo }) });
+            if (typeof response.token !== 'string' && response.token !== null) {
+                return { token: null, reason: 'unavailable' };
+            }
+            return {
+                token: response.token,
+                ...(typeof response.reason === 'string' ? { reason: response.reason } : {}),
+                ...(typeof response.message === 'string' ? { message: response.message } : {}),
+            };
+        }
+        catch {
+            return { token: null, reason: 'unavailable' };
+        }
+    }
+    claimNext(connectionId) {
+        return this.call(connectionId
+            ? `/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}`
+            : '/api/companion/tasks/next', CLAIM_TIMEOUT_MS, { headers: capabilityHeaders() });
+    }
+    async claimNextInvestigation() {
+        const response = await this.request('/api/companion/investigations/next', CLAIM_TIMEOUT_MS, {
+            headers: {
+                'X-Companion-Version': COMPANION_VERSION,
+                ...capabilityHeaders(),
+            },
+        });
+        if (response.status === 204)
+            return null;
+        return this.readResponse(response);
+    }
+    async registerConnection(identity) {
+        try {
+            return await this.call('/api/companion/connections/register', PAIRING_TIMEOUT_MS, {
+                method: 'POST',
+                body: JSON.stringify(identity),
+            });
+        }
+        catch (error) {
+            if (error instanceof CompanionHttpError) {
+                const code = error.message;
+                if (code === 'connection_ambiguous' || code === 'branch_conflict' || code === 'connection_limit') {
+                    throw new PairingHttpError(code);
+                }
+            }
+            throw new PairingHttpError('registration_failed');
+        }
+    }
+    async recordPairingOutcome(outcome) {
+        try {
+            return await this.call('/api/companion/pairing/outcome', PAIRING_TIMEOUT_MS, {
+                method: 'POST',
+                body: JSON.stringify({ outcome }),
+            });
+        }
+        catch {
+            throw new PairingHttpError('pairing_outcome_failed');
+        }
+    }
+    claimNextSurfaceMapping(connectionId) {
+        return this.call(`/api/companion/surface-mappings/next?connectionId=${encodeURIComponent(connectionId)}`, CLAIM_TIMEOUT_MS, {
+            headers: {
+                'X-Companion-Version': COMPANION_VERSION,
+                ...capabilityHeaders(),
+            },
+        });
+    }
+    reportSurfaceMappingResult(job, manifest) {
+        return this.call(`/api/companion/surface-mappings/${encodeURIComponent(job.jobId)}/result`, RESULT_TIMEOUT_MS, {
+            method: 'POST',
+            headers: {
+                'X-Companion-Version': COMPANION_VERSION,
+                ...capabilityHeaders(),
+            },
+            body: JSON.stringify({
+                attempt: job.attempt,
+                claimToken: job.claimToken,
+                resultKey: job.resultKey,
+                manifestHash: manifestHash(manifest),
+                manifest,
+            }),
+        });
+    }
+    reportSurfaceMappingError(job, error) {
+        return this.call(`/api/companion/surface-mappings/${encodeURIComponent(job.jobId)}/error`, ERROR_REPORT_TIMEOUT_MS, {
+            method: 'POST',
+            headers: {
+                'X-Companion-Version': COMPANION_VERSION,
+                ...capabilityHeaders(),
+            },
+            body: JSON.stringify({
+                attempt: job.attempt,
+                claimToken: job.claimToken,
+                kind: error.kind,
+                code: error.code,
+                detail: error.detail,
+            }),
+        });
+    }
+    heartbeat(taskId) {
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/heartbeat`, HEARTBEAT_TIMEOUT_MS, { method: 'POST' });
+    }
+    reportResult(taskId, result, filesRead, snapshot) {
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/result`, RESULT_TIMEOUT_MS, {
+            method: 'POST',
+            headers: capabilityHeaders(),
+            body: JSON.stringify({ result, filesRead, ...(snapshot ? { snapshot } : {}) }),
+        });
+    }
+    reportGitRangeResult(taskId, result) {
+        const body = JSON.stringify({ result, filesRead: [] });
+        if (Buffer.byteLength(body, 'utf8') > 1_572_864) {
+            throw new Error('history_failed');
+        }
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/result`, RESULT_TIMEOUT_MS, { method: 'POST', headers: capabilityHeaders(), body });
+    }
+    reportError(taskId, error) {
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/error`, ERROR_REPORT_TIMEOUT_MS, { method: 'POST', headers: capabilityHeaders(), body: JSON.stringify({ error }) });
+    }
+    reportInvestigationResult(investigationId, result) {
+        return this.call(`/api/companion/investigations/${encodeURIComponent(investigationId)}/result`, RESULT_TIMEOUT_MS, { method: 'POST', headers: capabilityHeaders(), body: JSON.stringify(result) });
+    }
+    reportReadiness(report) {
+        return this.call('/api/companion/readiness', READINESS_TIMEOUT_MS, {
+            method: 'POST',
+            body: JSON.stringify(report),
+        });
+    }
+}