@clien-ai/mcp 0.2.0 → 0.3.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,8 +37,21 @@
  *     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
+ *     into its background — the traits that predict a switch decision — so a later
+ *     `interview_persona` reasons from the persona's real status quo.
+ *     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
@@ -38,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
@@ -52,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()
@@ -82,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
@@ -104,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 {
 }
@@ -113,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}`);
     }
@@ -150,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)
@@ -205,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()
@@ -233,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.'),
@@ -250,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)
@@ -258,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.
@@ -295,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) {
@@ -312,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)
@@ -376,25 +477,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.
@@ -436,7 +552,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) {
@@ -453,7 +569,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)
@@ -495,4 +612,296 @@ 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. Persona
+// forum grounding (`sources[]`) and identity grounding (`identityPriors` /
+// `identityProvenance`) live on `report_data.personas[]`, surfaced via
+// `get_report` — `get_persona` returns whatever `GET /api/personas/[id]` gives
+// (`toPersona`, which omits `sources[]` and the identity columns), so it does not
+// promise grounding fields.
+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 — persona grounding (forum sources + identity) lives ' +
+        'in `report_data`, read it via `get_report`.'),
+});
+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.');
+    }
+    const role = persona.role ? `, ${persona.role}` : '';
+    const company = persona.company ? ` at ${persona.company}` : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Persona "${persona.name ?? personaId}"${role}${company} (id: ${persona.id})` +
+                    `${persona.projectId ? ` in project ${persona.projectId}` : ''}. ` +
+                    'Full fields are in `_meta.persona`.',
+            },
+        ],
+        _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