@clien-ai/mcp 0.2.1 → 0.4.0

package/dist/tools/personas.js

@@ -8,10 +8,23 @@
  * per-endpoint timeouts) exactly as `projects.ts` and `status.ts` do. No new
  * HTTP machinery.
  *
+ * Params are snake_case (`project_id`, `company_size`) — matching every other
+ * tool — and translated to the camelCase the REST API expects at the call site.
+ * FUL-233: the pre-migration camelCase spellings stay accepted as deprecated
+ * aliases, declared in the schema and rewritten before parse; see
+ * `param-aliases.ts` for the mechanism and the `*_ALIASES` maps below for which
+ * spellings each tool honours.
+ * FUL-238: because an alias is a separate OPTIONAL property, it cannot satisfy
+ * the advert's `required` list — so the three ids that have an alias
+ * (`create_persona`/`generate_persona` `project_id`, `enrich_persona`
+ * `persona_id`) are declared `.optional()` and their presence is enforced in the
+ * handler by `requireId`, keeping an alias-only payload valid against the
+ * advertised schema. See `requireId` for the full rationale.
+ *
  * Contract:
  *   - create_persona → POST /api/personas
  *       { projectId, name, role, company?, description?, companySize?,
- *         industry?, location?, ephemeral? } → 201 { persona }.
+ *         industry?, location?, ephemeral? } → 201 { persona }  (API body names).
  *       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
@@ -24,7 +37,7 @@
  *     so `source='mcp'` + `ephemeral` behave identically to the explicit create.
  *     FUL-96: by default it also grounds the persona in REAL user-voice evidence
  *     (Exa forums + Stack Exchange) and returns the source receipts in
- *     `_meta.sources`; pass `groundInEvidence: false` to skip retrieval. Grounding
+ *     `_meta.sources`; pass `ground_in_evidence: false` to skip retrieval. Grounding
  *     adds no extra credit cost (the Exa call is COGS).
  *     FUL-101 (M3a): the generated persona also carries a decision endowment
  *     (current tool, typical spend, switching cost, who-pays-vs-who-uses) folded
@@ -33,6 +46,12 @@
  *     FUL-102 (M3b): it also carries a credibility domain ("credible on X — not
  *     beyond") folded into the background, an honest bound on what the persona can
  *     speak to (Chuang transfer rule).
+ *     FUL-150 (M5b): it also generates identity priors — seniority rung + career
+ *     trajectory — persisted to the structured `personas.seniority` /
+ *     `personas.career_path` columns (the demographic shape of the role). Unlike
+ *     endowment/scope (folded into `background`), these are NOT echoed in the
+ *     returned persona object — they are a write-only persistence target that
+ *     M5c later reads back to calibrate against aggregate people distributions.
  *   - `enrich_persona` (FUL-77) — AI-fills the blank (or explicitly refreshed)
  *     scalar fields of an EXISTING persona over `POST /api/personas/ai-enrich`.
  *     Debits one `enrich_persona` credit, refunded if the enrichment fails; a
@@ -45,6 +64,7 @@
  */
 import { z } from 'zod';
 import { ToolError } from './errors.js';
+import { deprecatedAlias } from './param-aliases.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
@@ -59,12 +79,20 @@ const DESCRIPTION_MAX = 5000;
 const COMPANY_SIZE_MAX = 100;
 const INDUSTRY_MAX = 100;
 const LOCATION_MAX = 200;
+/** FUL-233: legacy camelCase spellings `create_persona` still accepts. */
+export const CREATE_PERSONA_ALIASES = {
+    projectId: 'project_id',
+    companySize: 'company_size',
+};
 export const CreatePersonaInputSchema = z.object({
-    projectId: z
+    project_id: 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). ' +
+        .optional()
+        .describe('REQUIRED — pass `project_id` (or its deprecated alias `projectId`); the call is rejected ' +
+        'if neither is present. It is absent from this schema\'s `required` list only so an ' +
+        'alias-only call stays valid. 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()
@@ -89,9 +117,9 @@ export const CreatePersonaInputSchema = z.object({
         .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
+    company_size: z
         .string()
-        .max(COMPANY_SIZE_MAX, `companySize too long (max ${COMPANY_SIZE_MAX} chars)`)
+        .max(COMPANY_SIZE_MAX, `company_size too long (max ${COMPANY_SIZE_MAX} chars)`)
         .optional()
         .describe('Optional company size (e.g. "11-50", "Enterprise").'),
     industry: z
@@ -111,6 +139,9 @@ export const CreatePersonaInputSchema = z.object({
         .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.'),
+    // --- Deprecated camelCase aliases (FUL-233) — rewritten before parse. ---
+    projectId: deprecatedAlias('project_id', z.string().uuid()),
+    companySize: deprecatedAlias('company_size', z.string().max(COMPANY_SIZE_MAX, `companySize too long (max ${COMPANY_SIZE_MAX} chars)`)),
 });
 export class PersonaToolError extends ToolError {
 }
@@ -120,33 +151,77 @@ function formatZodError(error) {
 function makeCtx(deps) {
     return { config: deps.config, session: deps.session, fetch: deps.fetch ?? fetch };
 }
+/**
+ * Presence check for an id that is `.optional()` in the Zod schema but mandatory
+ * in practice (FUL-238).
+ *
+ * Why optional-then-checked rather than plainly required: a required field lands
+ * in the advert's `required` list, and its deprecated camelCase alias — which is
+ * a SEPARATE optional property — cannot satisfy it. So an alias-only payload was
+ * invalid against the advertised schema even though the server honoured it, and
+ * a client that pre-validates OUTGOING arguments would refuse to send the call.
+ * Dropping the id from `required` and enforcing it here makes the advert accept
+ * every payload the runtime accepts. The cost is the advert's "this field is
+ * mandatory" signal, so each id's `.describe()` says REQUIRED in prose instead.
+ *
+ * Deliberately NOT a Zod `.refine()`/`.superRefine()`: those yield a `ZodEffects`
+ * with no `.shape`, which both `zodToInputSchema` and
+ * `__tests__/schema-contract.test.ts` depend on — the same convention
+ * `interview_persona` (per-action ids) and `update_persona` (at-least-one-field)
+ * already follow. Cross-field and presence rules live in plain code.
+ *
+ * Runs after `normalizeParamAliases` (applied by `defineTool` in `registry.ts`),
+ * so by the time it sees the input an alias-only call has already been rewritten
+ * onto the canonical name — and before any HTTP call, so a missing id never
+ * writes anything.
+ *
+ * `undefined` is the only "absent": Zod rejects an explicit `null` for a
+ * `.string().uuid()` before this runs.
+ */
+function requireId(value, canonical, alias) {
+    if (value === undefined) {
+        throw new PersonaToolError(`Invalid input — \`${canonical}\` is required. Pass \`${canonical}\` ` +
+            `(or its deprecated alias \`${alias}\`).`);
+    }
+    return value;
+}
 /**
  * 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.
+ * rebuilds from disk) and surfaces a re-auth message; 403 `PERSONA_LOCKED`
+ * surfaces an upgrade message (a locked persona/project is read-only); 404 means
+ * the caller does not own the target (the default message points at the project;
+ * pass `notFound` for a persona-scoped 404); 400 surfaces the server's
+ * validation detail; everything else surfaces a generic HTTP error.
+ *
+ * The body is parsed BEFORE the 404 branch so the 403 lock case can key on the
+ * `PERSONA_LOCKED` code the PATCH route returns.
  */
-async function throwForResponse(response, deps, action) {
+async function throwForResponse(response, deps, action, options) {
     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);
+    let parsed = null;
     try {
-        const parsed = JSON.parse(text);
-        if (parsed?.error)
-            detail = `${parsed.error}${parsed.code ? ` (${parsed.code})` : ''}`;
+        parsed = JSON.parse(text);
     }
     catch {
-        // non-JSON body — fall back to the truncated raw text
+        // non-JSON body — fall back to the truncated raw text below.
+    }
+    if (response.status === 403 && parsed?.code === 'PERSONA_LOCKED') {
+        throw new PersonaToolError(`Could not ${action} — it is locked due to subscription limits. Upgrade to Pro to edit it.`);
     }
+    if (response.status === 404) {
+        throw new PersonaToolError(options?.notFound ??
+            `Could not ${action} — project not found, or you don't own it. ` +
+                'Call list_projects to confirm the project_id.');
+    }
+    let detail = truncate(text, 200);
+    if (parsed?.error)
+        detail = `${parsed.error}${parsed.code ? ` (${parsed.code})` : ''}`;
     if (response.status === 400) {
         throw new PersonaToolError(`Could not ${action} — ${detail}`);
     }
@@ -157,7 +232,8 @@ export async function createPersona(input, deps) {
     if (!parsed.success) {
         throw new PersonaToolError(`Invalid input — ${formatZodError(parsed.error)}`);
     }
-    const { projectId, name, role, company, description, companySize, industry, location, ephemeral } = parsed.data;
+    const { project_id: rawProjectId, name, role, company, description, company_size: companySize, industry, location, ephemeral, } = parsed.data;
+    const projectId = requireId(rawProjectId, 'project_id', 'projectId');
     const ctx = makeCtx(deps);
     const body = { projectId, name, role, ephemeral };
     if (company !== undefined)
@@ -212,12 +288,22 @@ const GENERATE_PERSONA_FETCH_TIMEOUT_MS = 60_000;
 // Local cap, kept in sync with GeneratePersonaSchema in
 // app/api/personas/ai-generate/route.ts. The server re-validates regardless.
 const ADDITIONAL_CONTEXT_MAX = 2000;
+/** FUL-233: legacy camelCase spellings `generate_persona` still accepts. */
+export const GENERATE_PERSONA_ALIASES = {
+    projectId: 'project_id',
+    companySize: 'company_size',
+    additionalContext: 'additional_context',
+    groundInEvidence: 'ground_in_evidence',
+};
 export const GeneratePersonaInputSchema = z.object({
-    projectId: z
+    project_id: z
         .string()
         .uuid()
-        .describe('UUID of the project this persona belongs to. Get it from `list_projects` ' +
-        '(or `create_project`). Rejected with a 404 if you do not own the project.'),
+        .optional()
+        .describe('REQUIRED — pass `project_id` (or its deprecated alias `projectId`); the call is rejected ' +
+        'if neither is present. It is absent from this schema\'s `required` list only so an ' +
+        'alias-only call stays valid. UUID of the project this persona belongs to. Get it from ' +
+        '`list_projects` (or `create_project`). Rejected with a 404 if you do not own the project.'),
     name: z
         .string()
         .trim()
@@ -240,14 +326,14 @@ export const GeneratePersonaInputSchema = z.object({
         .max(INDUSTRY_MAX, `industry too long (max ${INDUSTRY_MAX} chars)`)
         .optional()
         .describe('Optional industry (e.g. "Fintech"). When omitted the AI infers one.'),
-    companySize: z
+    company_size: z
         .string()
-        .max(COMPANY_SIZE_MAX, `companySize too long (max ${COMPANY_SIZE_MAX} chars)`)
+        .max(COMPANY_SIZE_MAX, `company_size too long (max ${COMPANY_SIZE_MAX} chars)`)
         .optional()
         .describe('Optional company size (e.g. "11-50"). When omitted the AI infers one.'),
-    additionalContext: z
+    additional_context: z
         .string()
-        .max(ADDITIONAL_CONTEXT_MAX, `additionalContext too long (max ${ADDITIONAL_CONTEXT_MAX} chars)`)
+        .max(ADDITIONAL_CONTEXT_MAX, `additional_context too long (max ${ADDITIONAL_CONTEXT_MAX} chars)`)
         .optional()
         .describe('Optional free-form brief to steer generation — goals, constraints, the product being ' +
         'validated, or anything that should shape the persona\'s background and pain points.'),
@@ -257,7 +343,7 @@ export const GeneratePersonaInputSchema = z.object({
         .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).'),
-    groundInEvidence: z
+    ground_in_evidence: z
         .boolean()
         .optional()
         .default(true)
@@ -265,6 +351,13 @@ export const GeneratePersonaInputSchema = z.object({
         'from community forums + Stack Exchange for this role/industry, and returned with its ' +
         'source receipts. Set false to skip retrieval for a faster, invented-from-brief persona. ' +
         'Either way this debits one generate_persona credit; grounding adds no extra credit cost.'),
+    // --- Deprecated camelCase aliases (FUL-233) — rewritten before parse. ---
+    projectId: deprecatedAlias('project_id', z.string().uuid()),
+    companySize: deprecatedAlias('company_size', z.string().max(COMPANY_SIZE_MAX, `companySize too long (max ${COMPANY_SIZE_MAX} chars)`)),
+    additionalContext: deprecatedAlias('additional_context', z
+        .string()
+        .max(ADDITIONAL_CONTEXT_MAX, `additionalContext too long (max ${ADDITIONAL_CONTEXT_MAX} chars)`)),
+    groundInEvidence: deprecatedAlias('ground_in_evidence', z.boolean()),
 });
 /**
  * Map a non-ok POST /api/personas/ai-generate response to a PersonaToolError.
@@ -302,7 +395,7 @@ async function throwForGenerateResponse(response, deps) {
     }
     if (status === 404) {
         throw new PersonaToolError('Could not generate persona — project not found, or you don\'t own it. ' +
-            'Call list_projects to confirm the projectId.');
+            'Call list_projects to confirm the project_id.');
     }
     const detail = parsed?.error ? truncate(parsed.error, 200) : truncate(text, 200);
     if (status === 400) {
@@ -319,7 +412,8 @@ export async function generatePersona(input, deps) {
     if (!parsed.success) {
         throw new PersonaToolError(`Invalid input — ${formatZodError(parsed.error)}`);
     }
-    const { projectId, name, role, company, industry, companySize, additionalContext, ephemeral, groundInEvidence, } = parsed.data;
+    const { project_id: rawProjectId, name, role, company, industry, company_size: companySize, additional_context: additionalContext, ephemeral, ground_in_evidence: groundInEvidence, } = parsed.data;
+    const projectId = requireId(rawProjectId, 'project_id', 'projectId');
     const ctx = makeCtx(deps);
     const body = { projectId, name, role, ephemeral, groundInEvidence };
     if (company !== undefined)
@@ -364,12 +458,18 @@ export async function generatePersona(input, deps) {
         : sources.length > 0
             ? ` Grounded in ${sources.length} real source${sources.length === 1 ? '' : 's'} (user voice from forums + Stack Exchange).`
             : ' No matching real-world evidence was found, so it was generated from the brief.';
+    // FUL-243: render the GENERATED profile, not just a confirmation line. This
+    // tool's whole output is content the caller did not supply — the model wrote
+    // the background, company, industry, size and location — so a one-line receipt
+    // that points at `_meta.persona` means the agent cannot read what it just paid
+    // a credit to create. (`create_persona` / `update_persona` keep their
+    // confirmation lines: those only echo fields the agent itself passed in.)
     return {
         content: [
             {
                 type: 'text',
-                text: `Generated persona "${persona.name ?? name}" (${persona.role ?? role}, id: ${persona.id}) ` +
-                    `in project ${projectId} — debited 1 credit.${groundingNote}${insightsNote}`,
+                text: `Generated persona in project ${projectId} — debited 1 credit.` +
+                    `${groundingNote}${insightsNote}\n\n${renderPersonaProfile(persona, persona.id)}`,
             },
         ],
         _meta: { persona, sources },
@@ -383,25 +483,40 @@ const ENRICH_PERSONA_FETCH_TIMEOUT_MS = 60_000;
 // app/lib/personas/enrich-with-credits.ts (the @clien-ai/mcp package is published
 // separately and cannot import from the Next.js app). The server re-validates.
 const ENRICHABLE_FIELDS = ['description', 'company', 'industry', 'companySize', 'location'];
+/** FUL-233: legacy camelCase spellings `enrich_persona` still accepts. */
+export const ENRICH_PERSONA_ALIASES = {
+    personaId: 'persona_id',
+    additionalContext: 'additional_context',
+};
 export const EnrichPersonaInputSchema = z.object({
-    personaId: z
+    persona_id: z
         .string()
         .uuid()
-        .describe('UUID of the persona to enrich. Get it from a persona\'s `_meta.persona.id` ' +
-        '(e.g. from `create_persona`) or `list_projects`. Rejected with a 404 if you do not own it.'),
+        .optional()
+        .describe('REQUIRED — pass `persona_id` (or its deprecated alias `personaId`); the call is rejected ' +
+        'if neither is present. It is absent from this schema\'s `required` list only so an ' +
+        'alias-only call stays valid. UUID of the persona to enrich. Get it from a ' +
+        '`list_personas` entry or a persona\'s `_meta.persona.id` (e.g. from `create_persona`). ' +
+        'Rejected with a 404 if you do not own it.'),
     refresh: z
         .array(z.enum(ENRICHABLE_FIELDS))
         .optional()
         .describe('Optional list of already-populated fields to REGENERATE. By default enrich only fills ' +
         'fields that are currently blank and never overwrites existing content; pass e.g. ' +
-        '["description", "industry"] to force those to be regenerated. Valid values: ' +
-        'description, company, industry, companySize, location.'),
-    additionalContext: z
+        '["description", "industry"] to force those to be regenerated. These are persona ENTITY ' +
+        'field names, not param names, so `companySize` keeps its camelCase spelling here. ' +
+        'Valid values: description, company, industry, companySize, location.'),
+    additional_context: z
         .string()
-        .max(ADDITIONAL_CONTEXT_MAX, `additionalContext too long (max ${ADDITIONAL_CONTEXT_MAX} chars)`)
+        .max(ADDITIONAL_CONTEXT_MAX, `additional_context too long (max ${ADDITIONAL_CONTEXT_MAX} chars)`)
         .optional()
         .describe('Optional free-form brief to steer the enrichment — the product/market being validated, ' +
         'constraints, or anything that should shape the filled-in background and details.'),
+    // --- Deprecated camelCase aliases (FUL-233) — rewritten before parse. ---
+    personaId: deprecatedAlias('persona_id', z.string().uuid()),
+    additionalContext: deprecatedAlias('additional_context', z
+        .string()
+        .max(ADDITIONAL_CONTEXT_MAX, `additionalContext too long (max ${ADDITIONAL_CONTEXT_MAX} chars)`)),
 });
 /**
  * Map a non-ok POST /api/personas/ai-enrich response to a PersonaToolError.
@@ -443,7 +558,7 @@ async function throwForEnrichResponse(response, deps) {
     }
     if (status === 404) {
         throw new PersonaToolError('Could not enrich persona — persona not found, or you don\'t own it. ' +
-            'Confirm the personaId (e.g. from create_persona\'s _meta.persona.id).');
+            'Confirm the persona_id (e.g. from list_personas, or create_persona\'s _meta.persona.id).');
     }
     const detail = parsed?.error ? truncate(parsed.error, 200) : truncate(text, 200);
     if (status === 400) {
@@ -460,7 +575,8 @@ export async function enrichPersona(input, deps) {
     if (!parsed.success) {
         throw new PersonaToolError(`Invalid input — ${formatZodError(parsed.error)}`);
     }
-    const { personaId, refresh, additionalContext } = parsed.data;
+    const { persona_id: rawPersonaId, refresh, additional_context: additionalContext, } = parsed.data;
+    const personaId = requireId(rawPersonaId, 'persona_id', 'personaId');
     const ctx = makeCtx(deps);
     const body = { personaId };
     if (refresh !== undefined)
@@ -492,9 +608,14 @@ export async function enrichPersona(input, deps) {
     const enriched = Array.isArray(json?.enriched) ? json.enriched : [];
     const balance = typeof json?.balance === 'number' ? json.balance : null;
     const remaining = balance !== null ? ` ${balance} credit${balance === 1 ? '' : 's'} remaining.` : '';
+    // FUL-243: on a real enrichment, render the resulting profile — the filled
+    // fields are model-written content the agent has no other way to read (the
+    // `_meta.persona` it used to be pointed at is dropped by Claude Code). The
+    // no-op branch stays a one-liner: nothing changed, so there is nothing new
+    // to show.
     const text = enriched.length > 0
-        ? `Enriched persona "${persona.name ?? personaId}" (id: ${persona.id}) — filled ` +
-            `${enriched.join(', ')}. Debited 1 credit.${remaining}`
+        ? `Enriched persona (id: ${persona.id}) — filled ${enriched.join(', ')}. ` +
+            `Debited 1 credit.${remaining}\n\n${renderPersonaProfile(persona, personaId)}`
         : `Persona "${persona.name ?? personaId}" (id: ${persona.id}) was already fully populated — ` +
             'nothing enriched, no credit charged. Pass `refresh` to regenerate specific fields.';
     return {
@@ -502,4 +623,395 @@ export async function enrichPersona(input, deps) {
         _meta: { persona, enriched, balance },
     };
 }
+// ---------------------------------------------------------------------------
+// list_personas + get_persona (FUL-213 / §U2) — read-only entity discovery
+// ---------------------------------------------------------------------------
+//
+// The keystone read surface: `list_personas` discovers persona IDs in a project
+// (including personas created in the WEB app, previously unreachable from an
+// agent), and `get_persona` fetches one entity for correction/interview. Both
+// are read-only over the existing bearer endpoints — zero credit cost, zero side
+// effects — mirroring `list_reports`/`get_report`.
+//
+// NOTE: this is the entity-discovery surface, NOT the grounding surface — with
+// one exception. FUL-208: `toPersona` now maps the M5b identity columns, so both
+// tools return FLAT `persona.seniority` / `persona.careerPath` strings when the
+// run populated them (absent otherwise; read-only — see `update_persona`). Forum
+// grounding (`sources[]`) and the report-level `identityProvenance` are still
+// `report_data.personas[]` only, read via `get_report` — and the shape differs
+// there: the same two leaf names are NESTED under `identityPriors`.
+const LIST_LIMIT_MAX = 100;
+const LIST_LIMIT_DEFAULT = 20;
+export const ListPersonasInputSchema = z.object({
+    project_id: z
+        .string()
+        .uuid()
+        .describe('UUID of the project whose personas to list. Get it from `list_projects` ' +
+        '(or `create_project`). Rejected with a 404 if you do not own the project. ' +
+        'Lists personas created via the web app too, so you can discover a persona ' +
+        'id to pass to `get_persona`, `update_persona`, `enrich_persona`, or `interview_persona`.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(LIST_LIMIT_MAX)
+        .optional()
+        .default(LIST_LIMIT_DEFAULT)
+        .describe(`Maximum number of personas to return (1-${LIST_LIMIT_MAX}, default ${LIST_LIMIT_DEFAULT}). ` +
+        'Newest personas come first.'),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .default(0)
+        .describe('Number of personas to skip before returning results (default 0). ' +
+        'Combine with `limit` to page through a large persona list; the total ' +
+        'count is returned in `_meta.pagination.total`.'),
+});
+export const GetPersonaInputSchema = z.object({
+    persona_id: z
+        .string()
+        .uuid()
+        .describe('UUID of the persona to fetch. Get it from a `list_personas` entry (or a ' +
+        'persona\'s `_meta.persona.id`). Rejected with a 404 if you do not own it. ' +
+        'Returns the persona ENTITY (name, role, company, industry, etc.) for ' +
+        'discovery/correction, including read-only `seniority` / `careerPath` when ' +
+        'the persona has identity grounding. Forum sources and `identityProvenance` ' +
+        'live in `report_data`, read them via `get_report`.'),
+});
+/**
+ * Render a persona's FULL profile into readable text (FUL-243).
+ *
+ * Before this, `get_persona` returned ONE line — name, role, company, id — and
+ * pointed at `_meta.persona` for everything else. `_meta` is an optional host
+ * channel that Claude Code drops, so an agent about to interview a persona could
+ * not read the persona: no background, no industry, no location, no lock state.
+ * The whole profile now lands in the text, which every host delivers.
+ *
+ * Written as compact labelled lines rather than a JSON dump: the reader is a
+ * model, and labelled prose costs fewer tokens than pretty-printed JSON while
+ * staying unambiguous. Empty fields are OMITTED rather than rendered as "none" —
+ * a blank `industry` is unknown, and printing "Industry: none" would assert
+ * something the API never said.
+ *
+ * ⚠️ `includeInInsights` is deliberately NOT rendered. It is a phantom field on
+ * `interface Persona`: a write-path input on the app (`!ephemeral` on POST) that
+ * no response ever maps back out, as the FUL-240 coupling test records. Rendering
+ * it would print an insights/ephemeral claim derived from a value that is always
+ * `undefined` — inventing a fact in agent-visible text, which is the exact bug
+ * class this change exists to fix. (FUL-242 removes the field outright.)
+ *
+ * The closing caveat mirrors `list_competitors`: it makes a reader UNDER-trust
+ * the record. Almost nothing here is evidence — with one exception since FUL-208.
+ * `seniority` / `careerPath` ARE identity grounding and are rendered above, but
+ * they are aggregate-calibrated rather than span-receipted, so the caveat names
+ * them explicitly as un-citable instead of claiming the record carries no
+ * grounding at all. Everything else still lives on `report_data`.
+ */
+export function renderPersonaProfile(persona, fallbackId) {
+    const id = persona.id ?? fallbackId;
+    const role = persona.role ? `, ${persona.role}` : '';
+    const company = persona.company ? ` at ${persona.company}` : '';
+    const header = `Persona "${persona.name ?? fallbackId}"${role}${company}`;
+    const lines = [header, `id: ${id}`];
+    if (persona.projectId)
+        lines.push(`project_id: ${persona.projectId}`);
+    // Profile attributes on one line — these are what an interviewer needs to
+    // frame a question, and they read better grouped than as five stanzas.
+    const attributes = [
+        persona.industry && `Industry: ${persona.industry}`,
+        persona.companySize && `Company size: ${persona.companySize}`,
+        persona.location && `Location: ${persona.location}`,
+    ].filter(Boolean);
+    if (attributes.length > 0)
+        lines.push(attributes.join(' · '));
+    // Provenance and mutability. `isLocked` is rendered whenever the API states it
+    // (`=== true` / `=== false`, not truthiness) because "locked" and "unknown" are
+    // genuinely different answers to "can I edit this?" — and an agent that assumes
+    // editable will meet a 403 from `update_persona`.
+    const stateBits = [
+        persona.source && `Source: ${persona.source}`,
+        persona.enhancementStatus && `Enhancement: ${persona.enhancementStatus}`,
+        persona.isLocked === true
+            ? 'LOCKED — read-only (subscription limit); `update_persona` and `enrich_persona` will be refused'
+            : persona.isLocked === false
+                ? 'Editable'
+                : null,
+        persona.validationJobId && `From research job: ${persona.validationJobId}`,
+    ].filter(Boolean);
+    if (stateBits.length > 0)
+        lines.push(stateBits.join(' · '));
+    // FUL-208 identity priors, rendered as their OWN line rather than folded into
+    // the attributes above. They differ in KIND from `industry`/`location`: those
+    // are plain profile fields, whereas these are agent-written and calibrated
+    // against an aggregate people distribution. Mixing them in would flatten that
+    // distinction exactly where the closing caveat has to speak about it precisely.
+    // Rendered here — not left to `_meta` — because `_meta` is the channel Claude
+    // Code drops, which is the whole reason this renderer exists.
+    const identity = [
+        persona.seniority && `Seniority: ${persona.seniority}`,
+        persona.careerPath && `Career path: ${persona.careerPath}`,
+    ].filter(Boolean);
+    if (identity.length > 0)
+        lines.push(identity.join(' · '));
+    if (persona.description)
+        lines.push(`\nBackground:\n${persona.description}`);
+    // Receipts only when the response actually carried them. Their ABSENCE is not
+    // rendered as "no receipts": `GET /api/personas/{id}` is an entity read and is
+    // not the grounding surface, so a missing `sources` here means "not returned by
+    // this endpoint", never "this persona is ungrounded". The caveat below covers it.
+    //
+    // Read through `Array.isArray` rather than the declared type: `Persona` mirrors
+    // a backend shape we do not control, so a reshaped `sources` that is not an
+    // array would throw on `.map` and take the whole `get_persona` result with it.
+    // Everything else here is a string read that degrades to "omitted"; this is the
+    // one field that could crash, so it gets the same treatment as the digest's
+    // defensive accessors.
+    const sources = Array.isArray(persona.sources) ? persona.sources : [];
+    if (sources.length > 0) {
+        const receipts = sources.map((source, i) => {
+            const platform = source?.platform ?? 'unknown platform';
+            const url = source?.url ?? '(no url)';
+            return `  ${i + 1}. ${platform} — ${url}`;
+        });
+        lines.push(`\nSource receipts carried on this record (${sources.length}):\n${receipts.join('\n')}`);
+    }
+    lines.push('\nTRUST: this is the persona ENTITY. Seniority and career path are the ONE piece of ' +
+        'grounding it carries, and they are aggregate-calibrated, never span-receipted — there is ' +
+        'no source to follow for them, so do not cite them as evidence. Forum receipts ' +
+        '(`sources[]`) and `identityProvenance` live on `report_data.personas[]` — read them with ' +
+        '`get_report`, which nests seniority and career path under `identityPriors`. Treat every ' +
+        'other field above as unverified profile data until checked there; an absent field here ' +
+        'means "not returned", not "empty".');
+    return lines.join('\n');
+}
+export async function listPersonas(input, deps) {
+    const parsed = ListPersonasInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new PersonaToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { project_id: projectId, limit, offset } = parsed.data;
+    const ctx = makeCtx(deps);
+    const query = new URLSearchParams({
+        projectId,
+        limit: String(limit),
+        offset: String(offset),
+    });
+    let response;
+    try {
+        response = await apiCall(ctx, 'GET', `/api/personas?${query.toString()}`, {
+            timeoutMs: PERSONAS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new PersonaToolError(`Listing personas timed out after ${PERSONAS_FETCH_TIMEOUT_MS / 1000}s. Try again in a moment.`);
+        }
+        throw err;
+    }
+    if (!response.ok)
+        await throwForResponse(response, deps, 'list personas');
+    const json = (await response.json().catch(() => null));
+    const personas = json?.personas ?? [];
+    const total = json?.pagination?.total ?? personas.length;
+    let text;
+    if (personas.length === 0) {
+        text =
+            offset > 0
+                ? `No personas at offset ${offset} in project ${projectId} (total: ${total}).`
+                : `No personas in project ${projectId}. Use create_persona or generate_persona to add one.`;
+    }
+    else {
+        const lines = personas.map((p) => {
+            const role = p.role ? ` (${p.role})` : '';
+            return `- ${p.name ?? '(unnamed)'}${role} — id: ${p.id ?? 'unknown'}`;
+        });
+        const shown = offset + personas.length;
+        const more = shown < total ? `\n\n${total - shown} more not shown — page with offset=${shown}.` : '';
+        text =
+            `Found ${total} persona${total === 1 ? '' : 's'} in project ${projectId}:\n${lines.join('\n')}${more}\n\n` +
+                'Use get_persona with an id to read one, update_persona to correct it, or interview_persona to interview it.';
+    }
+    return {
+        content: [{ type: 'text', text }],
+        _meta: { personas, pagination: json?.pagination ?? { limit, offset, total } },
+    };
+}
+export async function getPersona(input, deps) {
+    const parsed = GetPersonaInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new PersonaToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { persona_id: personaId } = parsed.data;
+    const ctx = makeCtx(deps);
+    let response;
+    try {
+        response = await apiCall(ctx, 'GET', `/api/personas/${personaId}`, {
+            timeoutMs: PERSONAS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new PersonaToolError(`Fetching the persona timed out after ${PERSONAS_FETCH_TIMEOUT_MS / 1000}s. Try again in a moment.`);
+        }
+        throw err;
+    }
+    if (!response.ok) {
+        await throwForResponse(response, deps, 'get persona', {
+            notFound: 'Could not get persona — persona not found, or you don\'t own it. ' +
+                'Confirm the persona_id (e.g. from list_personas).',
+        });
+    }
+    const json = (await response.json().catch(() => null));
+    const persona = json?.persona;
+    if (!persona?.id) {
+        throw new PersonaToolError('Persona fetch returned no persona; the operation may not have succeeded.');
+    }
+    return {
+        content: [{ type: 'text', text: renderPersonaProfile(persona, personaId) }],
+        _meta: { persona },
+    };
+}
+// ---------------------------------------------------------------------------
+// update_persona (FUL-210 / §U4) — correct explicit persona fields
+// ---------------------------------------------------------------------------
+//
+// Wraps the shipped `PATCH /api/personas/[personaId]` (explicit patch, bearer,
+// FREE/unmetered) — NOT `ai-enrich` (which is AI-filled + debits a credit). This
+// completes the read → correct → interview loop for a web-created persona without
+// leaving for the web UI. Identity priors (seniority/careerPath) are M5c-managed
+// and NOT patchable here.
+//
+// The "at least one field required" rule is enforced in the handler (not via a
+// Zod `.refine()`) so the schema stays a plain `ZodObject` — the registry type
+// and the schema-contract test both assume `.shape`, and a `.refine()` would
+// yield a `ZodEffects` (mirrors the convention documented in interview.ts).
+/**
+ * The scalar fields `update_persona` can patch: snake_case PARAM name → the
+ * camelCase field name the REST API body and the persona entity both use
+ * (mirrors `UpdatePersonaSchema`). Only `company_size` diverges; the rest are
+ * single-word and identical on both sides.
+ */
+const UPDATABLE_FIELDS = {
+    name: 'name',
+    role: 'role',
+    company: 'company',
+    description: 'description',
+    company_size: 'companySize',
+    industry: 'industry',
+    location: 'location',
+};
+/** Param names as the caller supplies them — used in caller-facing messages. */
+const UPDATABLE_PARAMS = Object.keys(UPDATABLE_FIELDS);
+/** FUL-233: legacy camelCase spellings `update_persona` still accepts. */
+export const UPDATE_PERSONA_ALIASES = { companySize: 'company_size' };
+export const UpdatePersonaInputSchema = z.object({
+    persona_id: z
+        .string()
+        .uuid()
+        .describe('UUID of the persona to update. Get it from a `list_personas` entry (or a ' +
+        'persona\'s `_meta.persona.id`). Rejected with a 404 if you do not own it.'),
+    name: z
+        .string()
+        .trim()
+        .min(1, 'name must be non-empty')
+        .max(NAME_MAX, `name too long (max ${NAME_MAX} chars)`)
+        .optional()
+        .describe('New name for the persona.'),
+    role: z
+        .string()
+        .trim()
+        .min(1, 'role must be non-empty')
+        .max(ROLE_MAX, `role too long (max ${ROLE_MAX} chars)`)
+        .optional()
+        .describe('New job title / role (e.g. fix a wrong role).'),
+    company: z
+        .string()
+        .max(COMPANY_MAX, `company too long (max ${COMPANY_MAX} chars)`)
+        .optional()
+        .describe('New company or organisation.'),
+    description: z
+        .string()
+        .max(DESCRIPTION_MAX, `description too long (max ${DESCRIPTION_MAX} chars)`)
+        .optional()
+        .describe('New background/bio (goals, pain points, context).'),
+    company_size: z
+        .string()
+        .max(COMPANY_SIZE_MAX, `company_size too long (max ${COMPANY_SIZE_MAX} chars)`)
+        .optional()
+        .describe('New company size (e.g. "11-50", "Enterprise").'),
+    industry: z
+        .string()
+        .max(INDUSTRY_MAX, `industry too long (max ${INDUSTRY_MAX} chars)`)
+        .optional()
+        .describe('New industry (e.g. "Fintech", "Healthcare").'),
+    location: z
+        .string()
+        .max(LOCATION_MAX, `location too long (max ${LOCATION_MAX} chars)`)
+        .optional()
+        .describe('New location (e.g. "Berlin, Germany").'),
+    // --- Deprecated camelCase aliases (FUL-233) — rewritten before parse. ---
+    companySize: deprecatedAlias('company_size', z.string().max(COMPANY_SIZE_MAX, `companySize too long (max ${COMPANY_SIZE_MAX} chars)`)),
+});
+export async function updatePersona(input, deps) {
+    const parsed = UpdatePersonaInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new PersonaToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { persona_id: personaId, ...rest } = parsed.data;
+    // "At least one field" is enforced here, not via `.refine()` (see the header
+    // comment): build the patch body from only the fields the caller supplied,
+    // translating each snake_case param to the API's camelCase body field.
+    const body = {};
+    for (const param of UPDATABLE_PARAMS) {
+        const value = rest[param];
+        if (value !== undefined)
+            body[UPDATABLE_FIELDS[param]] = value;
+    }
+    if (Object.keys(body).length === 0) {
+        throw new PersonaToolError('Invalid input — provide at least one field to update ' +
+            `(one of: ${UPDATABLE_PARAMS.join(', ')}).`);
+    }
+    const ctx = makeCtx(deps);
+    let response;
+    try {
+        response = await apiCall(ctx, 'PATCH', `/api/personas/${personaId}`, {
+            body,
+            timeoutMs: PERSONAS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new PersonaToolError(`Updating the persona timed out after ${PERSONAS_FETCH_TIMEOUT_MS / 1000}s. ` +
+                'It may or may not have been applied — call get_persona to check before retrying.');
+        }
+        throw err;
+    }
+    if (!response.ok) {
+        await throwForResponse(response, deps, 'update persona', {
+            notFound: 'Could not update persona — persona not found, or you don\'t own it. ' +
+                'Confirm the persona_id (e.g. from list_personas).',
+        });
+    }
+    const json = (await response.json().catch(() => null));
+    const persona = json?.persona;
+    if (!persona?.id) {
+        throw new PersonaToolError('Persona update returned no persona; the operation may not have succeeded.');
+    }
+    const updatedFields = Object.keys(body);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Updated persona "${persona.name ?? personaId}" (id: ${persona.id}) — ` +
+                    `set ${updatedFields.join(', ')}. No credit charged (explicit edit).`,
+            },
+        ],
+        _meta: { persona, updated: updatedFields },
+    };
+}
 //# sourceMappingURL=personas.js.map