hakira-mcp 0.1.0

package/dist/resources/finding.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from '../tools/context.js';
+export declare function registerFindingResource(server: McpServer, deps: ToolDeps): void;

package/dist/resources/finding.js

@@ -0,0 +1,24 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { withAuthRetry } from '../tools/wrap.js';
+// hakira://finding/<id> → GET /findings/:id (00 §3 row 6, owner-scoped). The
+// drill-down behind the summary links from get_audit_findings. A 404 / non-owner
+// returns an error JSON body (not a crash).
+export function registerFindingResource(server, deps) {
+    server.registerResource('finding', new ResourceTemplate('hakira://finding/{id}', { list: undefined }), { title: 'Hakira finding', mimeType: 'application/json' }, async (uri, variables) => {
+        const id = String(variables.id);
+        let payload;
+        try {
+            payload = await withAuthRetry(deps, () => deps.cp.getFinding(id));
+        }
+        catch (err) {
+            payload = errorBody(err);
+        }
+        return {
+            contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(payload) }],
+        };
+    });
+}
+function errorBody(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: 'not_available', message };
+}

package/dist/tools/cancel.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerCancel(server: McpServer, deps: ToolDeps): void;

package/dist/tools/cancel.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { wrap, textResult } from './wrap.js';
+export function registerCancel(server, deps) {
+    server.registerTool('cancel_audit', {
+        title: 'Cancel a running Hakira audit',
+        description: 'Request cancellation of a running audit. On success returns the audit\'s REAL status: ' +
+            '"canceled" if it stopped, or "ready"/"error" if it had already finished on its own ' +
+            '(both fine — nothing more to do). "provisioning" means it was not stoppable yet; ' +
+            'call cancel_audit again shortly. ' +
+            'On error: "not_cancelable" means this audit was not started through MCP (a web-app chat) — ' +
+            'do NOT retry, tell the user to stop it from the Hakira web app. "cancel_failed" means the ' +
+            'audit may STILL be running and still spending credits — retry, or tell the user to stop it ' +
+            'in the web app. Never report a cancel_failed audit as stopped. ' +
+            'NOTE: cancellation is not an instant hard stop — in-flight work may accrue a little more ' +
+            'spend until the agent halts. Do not present it as immediate.',
+        inputSchema: {
+            audit_id: z.string().describe('The audit_id to cancel.'),
+        },
+    }, async (args) => wrap(deps, async () => textResult(await deps.cp.cancelAudit(args.audit_id))));
+}

package/dist/tools/context.d.ts

@@ -0,0 +1,9 @@
+import type { CpClient } from '../http/cp-client.js';
+/** Dependencies every tool handler is built with (injectable for tests). */
+export interface ToolDeps {
+    cp: CpClient;
+    resolveToken: () => Promise<string>;
+    clearCredentials: () => void;
+    /** The coding agent's project root (usually process.cwd()). */
+    root: string;
+}

package/dist/tools/context.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/get-audit-events.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerGetEvents(server: McpServer, deps: ToolDeps): void;

package/dist/tools/get-audit-events.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { wrap, textResult } from './wrap.js';
+export function registerGetEvents(server, deps) {
+    server.registerTool('get_audit_events', {
+        title: 'Read the live transcript of a Hakira audit',
+        description: 'Free. Activity trail of what Hakira has done / is doing: coalesced assistant text, collapsed tool runs ' +
+            '(e.g. Read ×N with sample paths), progress, findings. No tool result bodies — narrate from events, do not dump the JSON. ' +
+            'Use when the user asks to check an audit. Omit `after` for the latest page; pass `after: next_after` to continue. ' +
+            'Use get_audit_findings for full finding bodies; get_audit_status for coarse status/cost.',
+        inputSchema: {
+            audit_id: z.string().describe('The audit_id returned by start_audit.'),
+            // Keep schemas simple — Cursor silently drops tools whose JSON Schema
+            // includes Zod's Number.MAX_SAFE_INTEGER maximum from .int().nonnegative().
+            after: z
+                .number()
+                .optional()
+                .describe('Forward cursor (event id). Omit for the latest page (tail).'),
+            limit: z
+                .number()
+                .optional()
+                .describe('Max raw events per page (default 20, max 100).'),
+        },
+    }, async (args) => wrap(deps, async () => {
+        const after = typeof args.after === 'number' && Number.isFinite(args.after) && args.after >= 0
+            ? Math.floor(args.after)
+            : undefined;
+        const limit = typeof args.limit === 'number' && Number.isFinite(args.limit)
+            ? Math.max(1, Math.min(100, Math.floor(args.limit)))
+            : undefined;
+        return textResult(await deps.cp.getAuditEvents(args.audit_id, { after, limit }));
+    }));
+}

package/dist/tools/get-finding.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerGetFinding(server: McpServer, deps: ToolDeps): void;

package/dist/tools/get-finding.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { wrap, textResult } from './wrap.js';
+export function registerGetFinding(server, deps) {
+    server.registerTool('get_finding', {
+        title: 'Read full detail for one Hakira finding',
+        description: 'Free. Full finding body: description, evidence, recommendation (plus title/severity/target). ' +
+            'REQUIRED when the user asks what a finding is about, how to fix it, or for critical/high detail. ' +
+            'Do not invent detail from get_audit_findings titles alone — call this with the finding id.',
+        inputSchema: {
+            finding_id: z
+                .string()
+                .describe('Finding id from get_audit_findings (or the id in hakira://finding/<id>).'),
+        },
+    }, async (args) => wrap(deps, async () => textResult(await deps.cp.getFinding(args.finding_id))));
+}

package/dist/tools/get-findings.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerGetFindings(server: McpServer, deps: ToolDeps): void;

package/dist/tools/get-findings.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { wrap, textResult } from './wrap.js';
+const AGENT_INSTRUCTION = 'These are SUMMARIES only (title/severity/target) — not enough to explain or fix. ' +
+    'When the user asks what findings are about, for details, or for critical/high: ' +
+    'call get_finding for EACH relevant finding_id (or read hakira://finding/<id>). ' +
+    'Do not invent description/evidence/recommendation from titles.';
+export function registerGetFindings(server, deps) {
+    server.registerTool('get_audit_findings', {
+        title: 'List findings for a Hakira audit (summaries)',
+        description: 'Free. Summary list only: id, title, severity, category, target. ' +
+            'Does NOT include description, evidence, or recommendation. ' +
+            'When the user asks what findings are about, how to fix them, or for critical/high detail: ' +
+            'you MUST then call get_finding for each relevant id (prefer min_severity=critical or high first). ' +
+            'Optionally filter with min_severity.',
+        inputSchema: {
+            audit_id: z.string().describe('The audit_id from start_audit / list_audits.'),
+            min_severity: z
+                .string()
+                .optional()
+                .describe('Minimum severity to include: low | medium | high | critical.'),
+        },
+    }, async (args) => wrap(deps, async () => {
+        const findings = await deps.cp.getFindings(args.audit_id, {
+            min_severity: args.min_severity,
+        });
+        return textResult({
+            ...findings,
+            agent_instruction: AGENT_INSTRUCTION,
+        });
+    }));
+}

package/dist/tools/get-status.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerGetStatus(server: McpServer, deps: ToolDeps): void;

package/dist/tools/get-status.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { wrap, textResult } from './wrap.js';
+export function registerGetStatus(server, deps) {
+    server.registerTool('get_audit_status', {
+        title: 'Check the status of a Hakira audit',
+        description: 'Poll a running audit. Returns { status, phase?, findings_count, cost_so_far_usd, poll_after_ms }. ' +
+            'Statuses progress queued → provisioning → running → ready (or canceled / error). ' +
+            'When non-terminal, wait `poll_after_ms` before polling again.',
+        inputSchema: {
+            audit_id: z.string().describe('The audit_id returned by start_audit.'),
+        },
+    }, async (args) => wrap(deps, async () => textResult(await deps.cp.getStatus(args.audit_id))));
+}

package/dist/tools/list-audits.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerListAudits(server: McpServer, deps: ToolDeps): void;

package/dist/tools/list-audits.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { wrap, textResult } from './wrap.js';
+import { resolveRepoKey } from '../git/repo-key.js';
+export function registerListAudits(server, deps) {
+    server.registerTool('list_audits', {
+        title: 'List recent Hakira audits and sessions',
+        description: 'Free. List recent audits/sessions across your Hakira account (most recent first), with status, ' +
+            'workspace, origin (mcp|ui|gate), findings count and cost. `current_workspace_id` / `is_current` ' +
+            'mark the workspace bound to this local project. Optional `workspace_id` filters to one workspace. ' +
+            'Use get_audit_events / get_audit_status / get_audit_findings with any owned audit_id.',
+        inputSchema: {
+            workspace_id: z
+                .string()
+                .optional()
+                .describe('If set, only list sessions for this workspace. Omit for all workspaces.'),
+            limit: z.number().optional().describe('Max audits to return (default 20, max 100).'),
+        },
+    }, async (args) => wrap(deps, async () => {
+        await deps.resolveToken();
+        const repoKey = resolveRepoKey(deps.root);
+        const bind = await deps.cp.bindWorkspace(repoKey);
+        const current = bind.workspace_id;
+        const { audits } = await deps.cp.listAudits({
+            ...(args.workspace_id ? { workspace_id: args.workspace_id } : {}),
+            limit: args.limit,
+        });
+        return textResult({
+            current_workspace_id: current,
+            audits: audits.map((a) => ({
+                ...a,
+                is_current: a.workspace_id === current,
+            })),
+        });
+    }));
+}

package/dist/tools/list-workspaces.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerListWorkspaces(server: McpServer, deps: ToolDeps): void;

package/dist/tools/list-workspaces.js

@@ -0,0 +1,24 @@
+import { wrap, textResult } from './wrap.js';
+import { resolveRepoKey } from '../git/repo-key.js';
+export function registerListWorkspaces(server, deps) {
+    server.registerTool('list_workspaces', {
+        title: 'List all Hakira workspaces',
+        description: 'Free. List every workspace on your Hakira account. `current_workspace_id` / `is_current` mark ' +
+            'the workspace bound to this local project (via git remote / .hakira/mcp.json). Use list_audits ' +
+            'to see sessions; start_audit always runs on the current project workspace.',
+        inputSchema: {},
+    }, async () => wrap(deps, async () => {
+        await deps.resolveToken();
+        const repoKey = resolveRepoKey(deps.root);
+        const bind = await deps.cp.bindWorkspace(repoKey);
+        const current = bind.workspace_id;
+        const { workspaces } = await deps.cp.listWorkspaces();
+        return textResult({
+            current_workspace_id: current,
+            workspaces: workspaces.map((w) => ({
+                ...w,
+                is_current: w.workspace_id === current,
+            })),
+        });
+    }));
+}

package/dist/tools/resolve-run-mode.d.ts

@@ -0,0 +1,31 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ElicitRequestFormParams, ElicitResult } from '@modelcontextprotocol/sdk/types.js';
+export type RunMode = 'background' | 'wait';
+/** User declined/cancelled the background-vs-wait elicitation before spend. */
+export declare class RunModeCancelledError extends Error {
+    constructor(message?: string);
+}
+export declare const AGENT_INSTRUCTION: Record<RunMode, string>;
+export declare function modeResultFields(mode: RunMode): {
+    mode: RunMode;
+    do_not_poll: boolean;
+    agent_instruction: string;
+};
+/** Injectable surface so unit tests do not need a live MCP transport. */
+export interface RunModeElicitor {
+    getClientCapabilities(): {
+        elicitation?: unknown;
+    } | undefined;
+    elicitInput(params: ElicitRequestFormParams): Promise<ElicitResult>;
+}
+/**
+ * Resolve background vs wait for start_audit.
+ * - Explicit `mode` wins (skip elicitation).
+ * - Else, if the client supports elicitation, ask the user (decline/cancel aborts).
+ * - Else (or elicit failure): default to background.
+ */
+export declare function resolveRunMode(opts: {
+    mode?: RunMode;
+    server?: McpServer;
+    elicitor?: RunModeElicitor;
+}): Promise<RunMode>;

package/dist/tools/resolve-run-mode.js

@@ -0,0 +1,84 @@
+import { log } from '../log.js';
+/** User declined/cancelled the background-vs-wait elicitation before spend. */
+export class RunModeCancelledError extends Error {
+    constructor(message = 'Audit cancelled — choose background or wait to start.') {
+        super(message);
+        this.name = 'RunModeCancelledError';
+    }
+}
+export const AGENT_INSTRUCTION = {
+    background: 'Do NOT poll get_audit_status in a loop. Tell the user the audit_id and that they can ask later for status/findings. If they ask to check what Hakira is doing, call get_audit_events (omit after for the latest page). Continue the conversation.',
+    wait: 'Poll get_audit_status until ready (or canceled/error), waiting poll_after_ms between calls, then call get_audit_findings. Optionally call get_audit_events if the user asks what Hakira is doing mid-run.',
+};
+export function modeResultFields(mode) {
+    return {
+        mode,
+        do_not_poll: mode === 'background',
+        agent_instruction: AGENT_INSTRUCTION[mode],
+    };
+}
+const ELICIT_MESSAGE = 'How should this Hakira audit run? Background keeps this chat free (you can ask for status later). Wait blocks until findings are ready.';
+const ELICIT_SCHEMA = {
+    type: 'object',
+    properties: {
+        mode: {
+            type: 'string',
+            title: 'Run mode',
+            description: 'background = keep chatting; wait = poll this turn until ready',
+            enum: ['background', 'wait'],
+            default: 'background',
+        },
+    },
+    required: ['mode'],
+};
+function elicitorFromServer(server) {
+    return {
+        getClientCapabilities: () => server.server.getClientCapabilities(),
+        elicitInput: (params) => server.server.elicitInput(params),
+    };
+}
+function parseAcceptedMode(content) {
+    const raw = content?.mode;
+    if (raw === 'background' || raw === 'wait')
+        return raw;
+    return null;
+}
+/**
+ * Resolve background vs wait for start_audit.
+ * - Explicit `mode` wins (skip elicitation).
+ * - Else, if the client supports elicitation, ask the user (decline/cancel aborts).
+ * - Else (or elicit failure): default to background.
+ */
+export async function resolveRunMode(opts) {
+    if (opts.mode === 'background' || opts.mode === 'wait')
+        return opts.mode;
+    const elicitor = opts.elicitor ?? (opts.server ? elicitorFromServer(opts.server) : undefined);
+    if (!elicitor?.getClientCapabilities()?.elicitation) {
+        return 'background';
+    }
+    try {
+        const result = await elicitor.elicitInput({
+            mode: 'form',
+            message: ELICIT_MESSAGE,
+            requestedSchema: ELICIT_SCHEMA,
+        });
+        if (result.action === 'decline' || result.action === 'cancel') {
+            throw new RunModeCancelledError();
+        }
+        if (result.action === 'accept') {
+            const chosen = parseAcceptedMode(result.content);
+            if (chosen)
+                return chosen;
+            log.warn('elicitation accept missing mode — defaulting to background');
+            return 'background';
+        }
+        log.warn(`unexpected elicitation action ${String(result.action)} — defaulting to background`);
+        return 'background';
+    }
+    catch (err) {
+        if (err instanceof RunModeCancelledError)
+            throw err;
+        log.warn('elicitation failed — defaulting to background', err instanceof Error ? err.message : err);
+        return 'background';
+    }
+}

package/dist/tools/start-audit.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './context.js';
+export declare function registerStartAudit(server: McpServer, deps: ToolDeps): void;

package/dist/tools/start-audit.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { wrap, textResult } from './wrap.js';
+import { CpError } from '../http/errors.js';
+import { resolveRepoKey } from '../git/repo-key.js';
+import { captureGitMetadata, computeChangedFiles, buildTargetGist } from '../git/metadata.js';
+import { buildZip } from '../upload/zip.js';
+import { upload } from '../upload/presigned.js';
+import { config } from '../config.js';
+import { log } from '../log.js';
+import { modeResultFields, resolveRunMode } from './resolve-run-mode.js';
+// The one paid tool. Composes S2/S4/S5/S6/S7 into git → zip → upload → POST
+// /mcp/audits, returning a fast handle. Mode (background|wait) is chosen via
+// MCP elicitation when the host supports it, else defaults to background.
+const DESCRIPTION = [
+    'Start a Hakira cloud security audit of the current project.',
+    '',
+    'Spends credits: this is the only Hakira tool that does. `scope:"full"` (the default) is a',
+    'whole-project deep audit; `scope:"diff"` audits only the locally-changed files (shipped as a',
+    'prioritization hint) and costs a small fraction of a full audit. Optionally target a running',
+    'deployment with `url`.',
+    '',
+    'Returns immediately with { audit_id, status, mode, do_not_poll, agent_instruction }.',
+    '',
+    'IMPORTANT — `mode` argument:',
+    '- Do NOT pass `mode` unless the user explicitly said "background" or "wait".',
+    '- Omit `mode` so the host can elicit background vs wait (or default to background).',
+    '- Inventing `mode:"wait"` blocks the chat; inventing `mode:"background"` skips the user prompt.',
+    'When elicitation runs and the user cancels, the audit does not start.',
+    '',
+    'ALWAYS follow `agent_instruction` / `do_not_poll` in the result:',
+    '- background: do NOT poll; tell the user the audit_id; they can ask later for status/findings.',
+    '- wait: poll `get_audit_status` until `ready` (stop on canceled/error), then `get_audit_findings`.',
+].join('\n');
+export function registerStartAudit(server, deps) {
+    server.registerTool('start_audit', {
+        title: 'Start a Hakira cloud security audit',
+        description: DESCRIPTION,
+        inputSchema: {
+            scope: z
+                .enum(['full', 'diff'])
+                .optional()
+                .describe('`full` = whole-project deep audit (default). `diff` = prioritize changed files.'),
+            ref: z.string().optional().describe('Optional git ref (branch/tag/commit) to audit instead of the working tree.'),
+            url: z.string().optional().describe('Optional running target URL for dynamic testing alongside the source.'),
+            focus: z.string().optional().describe('Optional free-text focus, e.g. "auth flows" or "the payment webhook".'),
+            path: z.string().optional().describe('Optional sub-path within the repo to concentrate on.'),
+            mode: z
+                .enum(['background', 'wait'])
+                .optional()
+                .describe('ONLY if the user explicitly requested it. Omit otherwise so elicitation (or background default) can choose. Never invent wait/background.'),
+        },
+    }, async (args) => wrap(deps, async () => {
+        // Force auth (login / headless check) BEFORE the expensive zip+upload.
+        await deps.resolveToken();
+        const repoKey = resolveRepoKey(deps.root);
+        const meta = captureGitMetadata(deps.root, args.ref);
+        const bind = await deps.cp.bindWorkspace(repoKey);
+        if (bind.status === 'error') {
+            throw new CpError(409, {
+                error: 'workspace_needs_repair',
+                workspace_id: bind.workspace_id,
+                message: 'Workspace needs repair — cannot start an audit until it is repaired.',
+            }, 'Workspace needs repair');
+        }
+        // Paywall (P0): credits are purchased before the first audit. Fail fast
+        // HERE — before zip/upload/provision — so a broke user is sent straight to
+        // top-up instead of uploading a repo + booting a container that would be
+        // rejected server-side anyway (POST /mcp/audits enforces the same gate).
+        if (bind.balance_credits != null && bind.balance_credits <= 0) {
+            const url = bind.buy_credits_url ?? `${config.webUrl}/billing`;
+            throw new CpError(402, {
+                error: 'payment_required',
+                buy_credits_url: url,
+                message: `Insufficient credits — add credits at ${url} to start an audit.`,
+            }, 'Insufficient credits');
+        }
+        // HITL mode choice — after spend gates, before zip/upload so cancel is free.
+        const mode = await resolveRunMode({ server, mode: args.mode });
+        const scope = args.scope ?? 'full';
+        const changedFiles = scope === 'diff' ? computeChangedFiles(deps.root, { ref: args.ref }) : undefined;
+        const { buffer, manifest, excluded } = buildZip(deps.root, { ref: args.ref });
+        log.info(manifest);
+        const { r2_key } = await upload(deps.cp, bind.workspace_id, buffer, {
+            firstBind: !bind.bootstrapped,
+        });
+        const target = {
+            ref: args.ref,
+            url: args.url,
+            scope,
+            focus: args.focus,
+            path: args.path,
+            commit_sha: meta.commit_sha,
+            is_dirty: meta.is_dirty,
+            remote_url: meta.remote_url,
+            changed_files: changedFiles,
+            target_gist: buildTargetGist(meta, scope, changedFiles ?? []),
+        };
+        const res = await deps.cp.startAudit({ workspace_id: bind.workspace_id, r2_key, target });
+        // Include the manifest + excluded secret hits so the agent can relay what
+        // left the machine; full_project_estimate_usd is present only for full scope.
+        return textResult({
+            ...res,
+            scope,
+            ...modeResultFields(mode),
+            manifest,
+            excluded_from_upload: excluded,
+        });
+    }));
+}

package/dist/tools/wrap.d.ts

@@ -0,0 +1,13 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolDeps } from './context.js';
+export declare function textResult(payload: unknown): CallToolResult;
+export declare function errorResult(message: string): CallToolResult;
+/**
+ * Run `fn`, and on a `CpUnauthorizedError` clear the cached credential and retry
+ * exactly ONCE. The second failure (or any non-401) propagates to the caller,
+ * which maps it to its own shape. The single definition of the auth-retry
+ * contract — shared by tool handlers (`wrap`) and the finding resource.
+ */
+export declare function withAuthRetry<T>(deps: Pick<ToolDeps, 'clearCredentials'>, fn: () => Promise<T>): Promise<T>;
+/** Run a handler body with the uniform auth-retry + error mapping. */
+export declare function wrap(deps: ToolDeps, fn: () => Promise<CallToolResult>): Promise<CallToolResult>;

package/dist/tools/wrap.js

@@ -0,0 +1,89 @@
+import { CpError, CpUnauthorizedError } from '../http/errors.js';
+import { AuthorizationRequiredError } from '../auth/loopback.js';
+import { RunModeCancelledError } from './resolve-run-mode.js';
+import { log } from '../log.js';
+// Uniform error surfacing for every tool handler (ticket S3). A CpError becomes a
+// human-readable isError result; a 401 clears the cache + re-authorizes ONCE then
+// retries; a second 401 is a clean error (no loop); a headless AuthorizationRequired
+// is surfaced as the structured authorization_required shape (never hangs).
+export function textResult(payload) {
+    const text = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    return { content: [{ type: 'text', text }] };
+}
+export function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/**
+ * Run `fn`, and on a `CpUnauthorizedError` clear the cached credential and retry
+ * exactly ONCE. The second failure (or any non-401) propagates to the caller,
+ * which maps it to its own shape. The single definition of the auth-retry
+ * contract — shared by tool handlers (`wrap`) and the finding resource.
+ */
+export async function withAuthRetry(deps, fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof CpUnauthorizedError) {
+            log.warn('401 from CP — clearing cached credential and re-authorizing once');
+            deps.clearCredentials();
+            return await fn(); // a second failure propagates
+        }
+        throw err;
+    }
+}
+/** Run a handler body with the uniform auth-retry + error mapping. */
+export async function wrap(deps, fn) {
+    try {
+        return await withAuthRetry(deps, fn);
+    }
+    catch (err) {
+        // A CpUnauthorizedError here is necessarily the post-retry failure — a
+        // first-attempt 401 is always retried inside withAuthRetry.
+        return mapError(err, err instanceof CpUnauthorizedError);
+    }
+}
+function mapError(err, afterRetry) {
+    if (err instanceof RunModeCancelledError) {
+        return errorResult(err.message);
+    }
+    if (err instanceof AuthorizationRequiredError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'authorization_required',
+                        authorize_url: err.authorize_url,
+                        message: err.message,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (err instanceof CpUnauthorizedError) {
+        return errorResult(afterRetry
+            ? 'Authentication failed after re-authorization. Check HAKIRA_TOKEN, or run `hakira-mcp logout` and retry.'
+            : err.message);
+    }
+    if (err instanceof CpError) {
+        return errorResult(cpErrorText(err));
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return errorResult(`hakira-mcp error: ${message}`);
+}
+/** Ensure the human-readable message carries the structured id fields (00 §7). */
+function cpErrorText(err) {
+    let text = err.message;
+    if (err.error === 'audit_already_running' && err.audit_id && !text.includes(err.audit_id)) {
+        text += ` (audit_id: ${err.audit_id})`;
+    }
+    if (err.error === 'workspace_needs_repair' && err.workspace_id && !text.includes(err.workspace_id)) {
+        text += ` (workspace_id: ${err.workspace_id})`;
+    }
+    if (err.error === 'payment_required' && err.buy_credits_url && !text.includes(err.buy_credits_url)) {
+        text += ` Add credits: ${err.buy_credits_url}`;
+    }
+    return text;
+}

package/dist/upload/presigned.d.ts

@@ -0,0 +1,23 @@
+import type { CpClient } from '../http/cp-client.js';
+export interface UploadOptions {
+    firstBind: boolean;
+    excludeFolders?: string[];
+}
+/**
+ * Upload the ZIP and return the R2 key `start_audit` passes to POST /mcp/audits.
+ *
+ * On `firstBind` this uploads TWICE (00 §3 note / G5): once to drive the one-shot
+ * `/bootstrap` (consumed + deleted after AR extracts), then again for the scan's
+ * re-sync — the returned key is always a FRESH, unconsumed object.
+ *
+ * NON-BLOCKING (Option B): we do NOT wait for the first-bind bootstrap to finish.
+ * `completeUpload` enqueues it and returns; `start_audit` then POSTs to CP, which
+ * ACCEPTS the audit while the workspace is still provisioning and drives it via
+ * the deferred-kickoff worker once bootstrap completes. Honoring `start_audit`'s
+ * "returns immediately" promise is the whole point — the agent polls
+ * `get_audit_status` through provisioning → running → ready instead of the tool
+ * call blocking for the multi-minute provision window.
+ */
+export declare function upload(cp: CpClient, wsId: string, buffer: Buffer, opts: UploadOptions): Promise<{
+    r2_key: string;
+}>;