@clien-ai/mcp 0.1.3 → 0.1.5

package/dist/tools/personas.js

@@ -0,0 +1,192 @@
+/**
+ * `create_persona` — resource primitive over the Phase-0 personas REST API
+ * (`POST /api/personas`, built by FUL-16). Creates a persona row from explicit
+ * fields the caller already knows.
+ *
+ * The MCP package is a thin bearer-auth HTTP client: this tool reuses the
+ * shared `apiCall` client from `research.ts` (same 401→refresh→retry behavior,
+ * per-endpoint timeouts) exactly as `projects.ts` and `status.ts` do. No new
+ * HTTP machinery.
+ *
+ * Contract:
+ *   - create_persona → POST /api/personas
+ *       { projectId, name, role, company?, description?, companySize?,
+ *         industry?, location?, ephemeral? } → 201 { persona }.
+ *       Returns a confirmation line + the persona in `_meta.persona`.
+ *       The backend stamps `source='mcp'` automatically for bearer callers
+ *       (FUL-21). `ephemeral: true` sets `include_in_insights=false` so a
+ *       scratch persona is excluded from the project's aggregate insights.
+ *
+ * Scope note: this covers the explicit-field (free) create path only. The
+ * AI generate/enrich mode with a per-tool credit debit is deferred — its
+ * infrastructure (per-tool spend RPC, credit cost table, bearer auth on the AI
+ * generation routes) is not yet built. See the FUL-24 follow-up issue.
+ *
+ * Error mapping mirrors `projects.ts`: 401 → invalidate the cached session and
+ * surface a re-auth message; 404 → the project isn't owned by the caller;
+ * 400 → the server's validation message; other non-ok → a generic "HTTP <n>"
+ * error.
+ */
+import { z } from 'zod';
+import { ToolError } from './errors.js';
+import { apiCall, categorizeFetchError, truncate, } from './research.js';
+const PERSONAS_FETCH_TIMEOUT_MS = 30_000;
+// Caps re-declared locally: the @clien-ai/mcp package is published separately
+// and cannot import from the Next.js app. Kept in sync with `CreatePersonaSchema`
+// in app/api/personas/route.ts (name/role/company/location max 200, description
+// max 5000, companySize/industry max 100). The server re-validates regardless;
+// this is the advertised spec.
+const NAME_MAX = 200;
+const ROLE_MAX = 200;
+const COMPANY_MAX = 200;
+const DESCRIPTION_MAX = 5000;
+const COMPANY_SIZE_MAX = 100;
+const INDUSTRY_MAX = 100;
+const LOCATION_MAX = 200;
+export const CreatePersonaInputSchema = z.object({
+    projectId: z
+        .string()
+        .uuid()
+        .describe('UUID of the project this persona belongs to. Get it from `list_projects` ' +
+        '(or `create_project`, whose `_meta.project.id` you can pass straight in). ' +
+        'The persona is rejected with a 404 if you do not own the project.'),
+    name: z
+        .string()
+        .trim()
+        .min(1, 'name must be non-empty')
+        .max(NAME_MAX, `name too long (max ${NAME_MAX} chars)`)
+        .describe('The persona\'s name (e.g. "Priya, the pragmatic PM"). Short and human-readable.'),
+    role: z
+        .string()
+        .trim()
+        .min(1, 'role must be non-empty')
+        .max(ROLE_MAX, `role too long (max ${ROLE_MAX} chars)`)
+        .describe('The persona\'s job title or role (e.g. "Senior Product Manager"). Required.'),
+    company: z
+        .string()
+        .max(COMPANY_MAX, `company too long (max ${COMPANY_MAX} chars)`)
+        .optional()
+        .describe('Optional company or organisation the persona works at.'),
+    description: z
+        .string()
+        .max(DESCRIPTION_MAX, `description too long (max ${DESCRIPTION_MAX} chars)`)
+        .optional()
+        .describe('Optional background/bio for the persona: goals, pain points, context — ' +
+        'whatever helps an interview feel grounded. Stored as the persona\'s background.'),
+    companySize: z
+        .string()
+        .max(COMPANY_SIZE_MAX, `companySize too long (max ${COMPANY_SIZE_MAX} chars)`)
+        .optional()
+        .describe('Optional company size (e.g. "11-50", "Enterprise").'),
+    industry: z
+        .string()
+        .max(INDUSTRY_MAX, `industry too long (max ${INDUSTRY_MAX} chars)`)
+        .optional()
+        .describe('Optional industry (e.g. "Fintech", "Healthcare").'),
+    location: z
+        .string()
+        .max(LOCATION_MAX, `location too long (max ${LOCATION_MAX} chars)`)
+        .optional()
+        .describe('Optional location (e.g. "Berlin, Germany").'),
+    ephemeral: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Set true for a scratch/throwaway persona that should NOT count toward the ' +
+        'project\'s aggregate insights (sets include_in_insights=false). Leave false ' +
+        '(the default) for a real persona you want reflected in project-level analysis.'),
+});
+export class PersonaToolError extends ToolError {
+}
+function formatZodError(error) {
+    return error.issues.map((i) => `${i.path.join('.') || 'input'}: ${i.message}`).join('; ');
+}
+function makeCtx(deps) {
+    return { config: deps.config, session: deps.session, fetch: deps.fetch ?? fetch };
+}
+/**
+ * Shared non-ok handling: 401 drops the cached session (so the next tool call
+ * rebuilds from disk) and surfaces a re-auth message; 404 means the caller does
+ * not own the target project; 400 surfaces the server's validation detail;
+ * everything else surfaces a generic HTTP error.
+ */
+async function throwForResponse(response, deps, action) {
+    const category = categorizeFetchError(response.status);
+    if (category === 'auth') {
+        if (response.refreshError?.kind !== 'transient')
+            deps.invalidateSession?.();
+        throw new PersonaToolError('Session expired. Re-run any Clien.ai tool to re-authenticate, then try again.');
+    }
+    if (response.status === 404) {
+        throw new PersonaToolError(`Could not ${action} — project not found, or you don't own it. ` +
+            'Call list_projects to confirm the projectId.');
+    }
+    const text = await response.text().catch(() => '');
+    let detail = truncate(text, 200);
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed?.error)
+            detail = `${parsed.error}${parsed.code ? ` (${parsed.code})` : ''}`;
+    }
+    catch {
+        // non-JSON body — fall back to the truncated raw text
+    }
+    if (response.status === 400) {
+        throw new PersonaToolError(`Could not ${action} — ${detail}`);
+    }
+    throw new PersonaToolError(`Failed to ${action} (HTTP ${response.status}): ${detail}`);
+}
+export async function createPersona(input, deps) {
+    const parsed = CreatePersonaInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new PersonaToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { projectId, name, role, company, description, companySize, industry, location, ephemeral } = parsed.data;
+    const ctx = makeCtx(deps);
+    const body = { projectId, name, role, ephemeral };
+    if (company !== undefined)
+        body.company = company;
+    if (description !== undefined)
+        body.description = description;
+    if (companySize !== undefined)
+        body.companySize = companySize;
+    if (industry !== undefined)
+        body.industry = industry;
+    if (location !== undefined)
+        body.location = location;
+    let response;
+    try {
+        response = await apiCall(ctx, 'POST', '/api/personas', {
+            body,
+            timeoutMs: PERSONAS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new PersonaToolError(`Creating the persona timed out after ${PERSONAS_FETCH_TIMEOUT_MS / 1000}s. It may or may not have been created — call list_projects / check the project before retrying.`);
+        }
+        throw err;
+    }
+    if (!response.ok)
+        await throwForResponse(response, deps, 'create persona');
+    const json = (await response.json().catch(() => null));
+    const persona = json?.persona;
+    if (!persona?.id) {
+        throw new PersonaToolError('Persona creation returned no persona id; the operation may not have succeeded.');
+    }
+    const insightsNote = ephemeral
+        ? ' Marked ephemeral — excluded from project insights.'
+        : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Created persona "${persona.name ?? name}" (${persona.role ?? role}, id: ${persona.id}) ` +
+                    `in project ${projectId}.${insightsNote}`,
+            },
+        ],
+        _meta: { persona },
+    };
+}
+//# sourceMappingURL=personas.js.map

package/dist/tools/personas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personas.js","sourceRoot":"","sources":["../../src/tools/personas.ts"],"names":[],"mappings":"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"}

package/dist/tools/projects.js

@@ -0,0 +1,195 @@
+/**
+ * `list_projects` + `create_project` — resource primitives over the Phase-0
+ * projects REST API (`GET`/`POST /api/projects`, built by FUL-15).
+ *
+ * The MCP package is a thin bearer-auth HTTP client: these tools reuse the
+ * shared `apiCall` client from `research.ts` (same 401→refresh→retry behavior,
+ * per-endpoint timeouts) exactly as `status.ts` does. No new HTTP machinery.
+ *
+ * Contract:
+ *   - list_projects → GET /api/projects?limit&offset →
+ *       { projects: Project[], pagination: { limit, offset, total } }.
+ *       Returns a readable list as text + the raw arrays in `_meta` so a host
+ *       AI can pick a `project_id` to pass to `clien_research`.
+ *   - create_project → POST /api/projects { name, description? } →
+ *       201 { project }. Returns a confirmation line + the project in `_meta`.
+ *
+ * Error mapping mirrors `status.ts`: 401 → invalidate the cached session and
+ * surface a re-auth message; 400 → the server's validation message; other
+ * non-ok → a generic "HTTP <n>" error. All read/writes are cheap and
+ * idempotent-ish (create is the only mutation), so timeouts/network errors
+ * surface raw for the caller to retry.
+ */
+import { z } from 'zod';
+import { ToolError } from './errors.js';
+import { apiCall, categorizeFetchError, truncate, } from './research.js';
+const PROJECTS_FETCH_TIMEOUT_MS = 30_000;
+// Caps re-declared locally: the @clien-ai/mcp package is published separately
+// and cannot import from the Next.js app. Kept in sync with VALIDATION_LIMITS
+// (PROJECT_NAME_MAX=100, PROJECT_DESCRIPTION_MAX=1500) in
+// app/lib/constants/app.ts — matches the precedent set for `project_name` in
+// research.ts. The server re-validates regardless; this is the advertised spec.
+const PROJECT_NAME_MAX = 100;
+const PROJECT_DESCRIPTION_MAX = 1500;
+const LIST_LIMIT_MAX = 100;
+const LIST_LIMIT_DEFAULT = 20;
+export const ListProjectsInputSchema = z.object({
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(LIST_LIMIT_MAX)
+        .optional()
+        .default(LIST_LIMIT_DEFAULT)
+        .describe(`Maximum number of projects to return (1-${LIST_LIMIT_MAX}, default ${LIST_LIMIT_DEFAULT}). ` +
+        'Newest projects come first.'),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .default(0)
+        .describe('Number of projects to skip before returning results (default 0). ' +
+        'Combine with `limit` to page through a large project list; the ' +
+        'total count is returned in `_meta.pagination.total`.'),
+});
+export const CreateProjectInputSchema = z.object({
+    name: z
+        .string()
+        .trim()
+        .min(1, 'name must be non-empty')
+        .max(PROJECT_NAME_MAX, `name too long (max ${PROJECT_NAME_MAX} chars)`)
+        .describe('Human-readable name for the new project. Keep it short (2-4 words) — ' +
+        'typically the product or idea name. Use `list_projects` first to ' +
+        'avoid creating a duplicate of an existing project.'),
+    description: z
+        .string()
+        .max(PROJECT_DESCRIPTION_MAX, `description too long (max ${PROJECT_DESCRIPTION_MAX} chars)`)
+        .optional()
+        .describe('Optional longer description of what the project is about (max ' +
+        `${PROJECT_DESCRIPTION_MAX} chars). Omit if the name is self-explanatory.`),
+});
+export class ProjectToolError extends ToolError {
+}
+function formatZodError(error) {
+    return error.issues.map((i) => `${i.path.join('.') || 'input'}: ${i.message}`).join('; ');
+}
+function makeCtx(deps) {
+    return { config: deps.config, session: deps.session, fetch: deps.fetch ?? fetch };
+}
+/**
+ * Shared non-ok handling: 401 drops the cached session (so the next tool call
+ * rebuilds from disk) and surfaces a re-auth message; 400 surfaces the server's
+ * validation detail; everything else surfaces a generic HTTP error.
+ */
+async function throwForResponse(response, deps, action) {
+    const category = categorizeFetchError(response.status);
+    if (category === 'auth') {
+        if (response.refreshError?.kind !== 'transient')
+            deps.invalidateSession?.();
+        throw new ProjectToolError('Session expired. Re-run any Clien.ai tool to re-authenticate, then try again.');
+    }
+    const text = await response.text().catch(() => '');
+    let detail = truncate(text, 200);
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed?.error)
+            detail = `${parsed.error}${parsed.code ? ` (${parsed.code})` : ''}`;
+    }
+    catch {
+        // non-JSON body — fall back to the truncated raw text
+    }
+    if (response.status === 400) {
+        throw new ProjectToolError(`Could not ${action} — ${detail}`);
+    }
+    throw new ProjectToolError(`Failed to ${action} (HTTP ${response.status}): ${detail}`);
+}
+export async function listProjects(input, deps) {
+    const parsed = ListProjectsInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new ProjectToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { limit, offset } = parsed.data;
+    const ctx = makeCtx(deps);
+    let response;
+    try {
+        response = await apiCall(ctx, 'GET', `/api/projects?limit=${limit}&offset=${offset}`, {
+            timeoutMs: PROJECTS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new ProjectToolError(`Listing projects timed out after ${PROJECTS_FETCH_TIMEOUT_MS / 1000}s. Try again in a moment.`);
+        }
+        throw err;
+    }
+    if (!response.ok)
+        await throwForResponse(response, deps, 'list projects');
+    const json = (await response.json().catch(() => null));
+    const projects = json?.projects ?? [];
+    const total = json?.pagination?.total ?? projects.length;
+    let text;
+    if (projects.length === 0) {
+        text =
+            offset > 0
+                ? `No projects at offset ${offset} (total: ${total}).`
+                : 'No projects yet. Use create_project to make one, or run clien_research with a project_name.';
+    }
+    else {
+        const lines = projects.map((p) => {
+            const desc = p.description ? ` — ${truncate(p.description, 100)}` : '';
+            return `- ${p.name ?? '(unnamed)'} (id: ${p.id ?? 'unknown'})${desc}`;
+        });
+        const shown = offset + projects.length;
+        const more = shown < total ? `\n\n${total - shown} more not shown — page with offset=${shown}.` : '';
+        text = `Found ${total} project${total === 1 ? '' : 's'}:\n${lines.join('\n')}${more}`;
+    }
+    return {
+        content: [{ type: 'text', text }],
+        _meta: { projects, pagination: json?.pagination ?? { limit, offset, total } },
+    };
+}
+export async function createProject(input, deps) {
+    const parsed = CreateProjectInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new ProjectToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { name, description } = parsed.data;
+    const ctx = makeCtx(deps);
+    const body = { name };
+    if (description !== undefined)
+        body.description = description;
+    let response;
+    try {
+        response = await apiCall(ctx, 'POST', '/api/projects', {
+            body,
+            timeoutMs: PROJECTS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new ProjectToolError(`Creating the project timed out after ${PROJECTS_FETCH_TIMEOUT_MS / 1000}s. It may or may not have been created — call list_projects to check before retrying.`);
+        }
+        throw err;
+    }
+    if (!response.ok)
+        await throwForResponse(response, deps, 'create project');
+    const json = (await response.json().catch(() => null));
+    const project = json?.project;
+    if (!project?.id) {
+        throw new ProjectToolError('Project creation returned no project id; the operation may not have succeeded.');
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Created project "${project.name ?? name}" (id: ${project.id}). ` +
+                    'Pass this id as `project_id` to clien_research to attach research runs to it.',
+            },
+        ],
+        _meta: { project },
+    };
+}
+//# sourceMappingURL=projects.js.map

package/dist/tools/projects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../src/tools/projects.ts"],"names":[],"mappings":"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"}

package/dist/tools/registry.js

@@ -0,0 +1,147 @@
+/**
+ * Tool registry — the single source of truth for the MCP tool surface.
+ *
+ * Each entry is a self-contained `{ name, description, zodSchema, handler }`.
+ * `server.ts` iterates this array for BOTH `tools/list` (advertising the
+ * Zod-generated `jsonSchema`) and `tools/call` (dispatching to `handler`).
+ * Adding a tool is a one-line push here — no dispatch edits, no hand-rolled
+ * JSON Schema.
+ *
+ * `jsonSchema` is precomputed once at module load via `zodToInputSchema`.
+ * Handlers are thin arrows that call the imported tool function at call time
+ * (not captured references) so ESM live-bindings keep `vi.mock(...)` in the
+ * tests working.
+ */
+import { zodToInputSchema } from './schema.js';
+import { ResearchInputSchema, runResearch } from './research.js';
+import { StatusInputSchema, getResearchStatus } from './status.js';
+import { ListProjectsInputSchema, CreateProjectInputSchema, listProjects, createProject, } from './projects.js';
+import { CreatePersonaInputSchema, createPersona } from './personas.js';
+import { ListReportsInputSchema, GetReportInputSchema, listReports, getReport, } from './reports.js';
+import { InterviewPersonaInputSchema, interviewPersona } from './interview.js';
+function defineTool(def) {
+    return { ...def, jsonSchema: zodToInputSchema(def.zodSchema) };
+}
+export const TOOLS = [
+    defineTool({
+        name: 'clien_research',
+        description: 'Run a full product-research pass on an idea — the recommended default for validating ' +
+            'a new idea end to end. Returns a markdown report plus structured report_data ' +
+            '(hypotheses, competitors[], key findings). Typical wall time 15-25 minutes; progress ' +
+            'is streamed via notifications/progress. ' +
+            'This hero tool runs the whole curated pipeline in one call. PREFER it over hand-assembling ' +
+            'a full validation from the granular primitives (create_persona + interview_persona + get_report) — ' +
+            'those are for targeted, cheaper spot-checks, not a complete report; sequencing them yourself ' +
+            'gives lower-quality coverage. See docs/recipes/ for the supported compositions ' +
+            '(competitor spot-check, pivot viability, new-market persona validation). ' +
+            'First call opens a browser for one-time OAuth login; subsequent calls reuse the stored refresh token. ' +
+            'IMPORTANT: if this call fails mid-flight with "MCP error -32000: Connection closed", ' +
+            'do NOT call clien_research again — that spawns a new run and debits credits again for the same idea. ' +
+            'Instead call `clien_research_status` with the job_id from the prior call\'s `_meta.job_id` ' +
+            '(or from the `[clien-mcp] research started job_id=…` line in the MCP server\'s stderr log).',
+        zodSchema: ResearchInputSchema,
+        handler: (args, deps) => runResearch(args, deps),
+    }),
+    defineTool({
+        name: 'clien_research_status',
+        description: 'Fetch the current state of an existing `clien_research` job. Use this to ' +
+            'recover a run that disconnected with -32000 mid-flight (the job keeps running ' +
+            'on the backend; this tool re-attaches a read view) and to poll for completion. ' +
+            'If the job is complete, returns the full markdown report and structured report_data ' +
+            'in the same shape `clien_research` would have returned — no need to call research again. ' +
+            'If the job is still running, returns a brief status summary. If the job failed or ' +
+            'was cancelled, returns the failure reason. ' +
+            'RECOVERY WITHOUT A JOB_ID: if the -32000 drop left you with no job_id, call this tool ' +
+            'with NO arguments — it discovers your recent run(s). If exactly one is in flight it ' +
+            'resumes it automatically; if several come back, it returns a list of runs each with a ' +
+            'job_id and an idea snippet — re-call with the job_id whose idea matches the run you were ' +
+            'executing (never guess, so run A never receives run B\'s report). ' +
+            'Read-only: no credit cost, no side effects.',
+        zodSchema: StatusInputSchema,
+        handler: (args, deps) => getResearchStatus(args, deps),
+    }),
+    defineTool({
+        name: 'list_projects',
+        description: 'List the caller\'s Clien.ai projects (newest first, paginated). Returns each ' +
+            'project\'s name and id as text, plus the raw project array and pagination in ' +
+            '`_meta`. Use this to find an existing `project_id` to attach a `clien_research` ' +
+            'run to, or to check whether a project already exists before calling `create_project`. ' +
+            'Read-only: no credit cost, no side effects.',
+        zodSchema: ListProjectsInputSchema,
+        handler: (args, deps) => listProjects(args, deps),
+    }),
+    defineTool({
+        name: 'create_project',
+        description: 'Create a new Clien.ai project to group research runs, personas, and reports. ' +
+            'Returns the created project (including its `id`) in `_meta.project`; pass that id ' +
+            'as `project_id` on subsequent `clien_research` calls. Prefer calling `list_projects` ' +
+            'first to avoid duplicates. Note: `clien_research` can also auto-create a project via ' +
+            'its `project_name` argument — use this tool when you want to create the project up ' +
+            'front (e.g. with a description) or without starting a research run.',
+        zodSchema: CreateProjectInputSchema,
+        handler: (args, deps) => createProject(args, deps),
+    }),
+    defineTool({
+        name: 'create_persona',
+        description: 'Create a persona (a target user/customer profile) in a Clien.ai project from ' +
+            'fields you already know. Returns the created persona (including its `id`) in ' +
+            '`_meta.persona`. Requires a `projectId` — call `list_projects` first to find one, ' +
+            'or `create_project` to make one. Provide `name` and `role` at minimum; add ' +
+            '`company`, `description` (background/goals/pain points), `companySize`, `industry`, ' +
+            'and `location` when you have them. Set `ephemeral: true` for a scratch persona you ' +
+            'do NOT want counted in the project\'s aggregate insights (e.g. a quick one-off). ' +
+            'Compose with `interview_persona` to validate a NEW MARKET cheaply: create a persona ' +
+            'representing that market, then interview it (see docs/recipes/new-market-persona-validation.md). ' +
+            'For a FULL validation report on the new market rather than a targeted probe, prefer `clien_research`. ' +
+            'This is a free, no-credit create for explicit fields — AI generation/enrichment of ' +
+            'persona details is not yet available via MCP, so supply the fields yourself.',
+        zodSchema: CreatePersonaInputSchema,
+        handler: (args, deps) => createPersona(args, deps),
+    }),
+    defineTool({
+        name: 'list_reports',
+        description: 'List the caller\'s past `clien_research` runs (newest first, paginated by `limit`). ' +
+            'Returns each report\'s prompt, status, and `job_id` as text, plus the raw job array in ' +
+            '`_meta.jobs`. Optionally scope to one project with `project_id`. Use this to find a ' +
+            'past report to retrieve with `get_report` instead of re-running `clien_research` — ' +
+            're-running spawns a new job and debits credits again for the same idea. Pair with ' +
+            '`get_report` for a free competitor spot-check (read `report_data.competitors[]` from a ' +
+            'recent run; see docs/recipes/competitor-spot-check.md). ' +
+            'Read-only: no credit cost, no side effects.',
+        zodSchema: ListReportsInputSchema,
+        handler: (args, deps) => listReports(args, deps),
+    }),
+    defineTool({
+        name: 'get_report',
+        description: 'Retrieve the full report for a past `clien_research` job by its `job_id` (from a prior ' +
+            'run\'s `_meta.job_id` or a `list_reports` entry). Returns the markdown report as text ' +
+            'plus structured `report_data` (hypotheses, competitors[], key findings) in `_meta` — ' +
+            'the same shape `clien_research` returns. Use this to RETRIEVE past research instead of ' +
+            're-running `clien_research`, which would debit credits again for the same idea. ' +
+            'Backs the competitor spot-check (read `report_data.competitors[]`) and pivot-viability ' +
+            '(compare a pivot\'s report against the original) recipes in docs/recipes/. ' +
+            'If the job is still running or you are unsure of its state, use `clien_research_status`. ' +
+            'Read-only: no credit cost, no side effects.',
+        zodSchema: GetReportInputSchema,
+        handler: (args, deps) => getReport(args, deps),
+    }),
+    defineTool({
+        name: 'interview_persona',
+        description: 'Run a real, stateful multi-turn interview with a persona and get its full replies. ' +
+            'Drive it as a loop: `action:start` once (with projectId + personaId) opens the interview ' +
+            'and seeds the persona\'s greeting, returning the interview id in `_meta.interview.id`. ' +
+            'Then `action:turn` (interviewId + content) repeatedly — each call posts one question and ' +
+            'returns THAT persona\'s full reply as the result text; read it, then ask the next question. ' +
+            '`action:transcript` (interviewId) re-reads the whole conversation. `action:complete` closes ' +
+            'the interview when you\'ve learned enough (5-12 turns is typical); `action:reopen` resumes a ' +
+            'completed one. Interviews and their auto-summary/message-count behave exactly like the web app. ' +
+            'Set `ephemeral:true` on `start` for a scratch interview excluded from the project\'s aggregate ' +
+            'insights. Compose with `create_persona` to validate a new market or pressure-test a pivot ' +
+            '(see docs/recipes/); for a FULL validation report, prefer `clien_research` over stitching ' +
+            'interviews together yourself. Each `turn` generates a real AI reply (metered by your monthly ' +
+            'usage; per-turn credit pricing is not yet applied).',
+        zodSchema: InterviewPersonaInputSchema,
+        handler: (args, deps) => interviewPersona(args, deps),
+    }),
+];
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}