@clien-ai/mcp 0.8.1 → 0.9.0

package/dist/tools/content-type-display.js

@@ -0,0 +1,166 @@
+/**
+ * FUL-341 / FUL-536 / FUL-560 — the one rule for reading and RENDERING a source's content type to
+ * an agent.
+ *
+ * ## Why this is a module and not two copies
+ *
+ * `list_community_signals` (`collections.ts`) and `search_forums` (`scoped-research.ts`) render the
+ * SAME underlying rows — a forum thread a run discovered, before and after it is promoted into
+ * `community_signals`. FUL-247's rule is that two surfaces over one dataset must not disagree about
+ * what is worth an agent's attention; FUL-536 is what happens when they do, and it took two green
+ * guards and a production run to notice. So the vocabulary, the fail-closed normalizer and the
+ * rendered line live in ONE place that both import, the same way `engagement-display.ts` owns the
+ * engagement line for the same two surfaces.
+ *
+ * ## The rule
+ *
+ * State the provenance in BOTH directions, always. Rendering a type only when one is present makes
+ * "unclassified" indistinguishable from "this surface was not told", and silence reads as
+ * reassurance — which is the fail-open FUL-341 exists to close. An agent deciding whether to trust
+ * a quote needs the negative case spelled out, and it needs the CONSEQUENCE, not just a null field.
+ *
+ * ⚠️ THE TWO EXCLUSIONS ARE THE SAME BUT ARE WORDED SEPARATELY ON PURPOSE. Since FUL-531 both kinds
+ * carry the identical exclusion — `GROUNDING_ELIGIBLE_CONTENT_TYPES` (`app/lib/db/community-db.ts`)
+ * is `CONTENT_TYPES` minus `FLAGGED_CONTENT_TYPES`, so neither reaches the automatic synthesis
+ * prompt, and `buildCommunityThemes` grounds no theme on either. They stay worded SEPARATELY
+ * because they do not MEAN the same thing: `marketing_seo` is a source we classified and judged
+ * vendor copy, `unclassified` is one nobody has looked at. Collapsing them would tell an agent that
+ * an unexamined source had been examined.
+ */
+/**
+ * FUL-341 — the canonical content-type vocabulary, hand-copied.
+ *
+ * `mcp/` publishes to npm on its own cadence and cannot import from the Next.js app, so this is a
+ * forced duplicate of `CONTENT_TYPES` in `app/lib/validation/claim-states.ts` (itself already
+ * pinned to the agent's copy). This repo's answer to exactly that situation is a coupling test:
+ * `__tests__/integration/mcp/community-content-type-coupling.test.ts` pins this set equal to the
+ * app's, so widening the vocabulary in one package fails the suite rather than silently teaching
+ * two surfaces to disagree about the same row.
+ *
+ * ⚠️ That test parses this declaration out of THIS FILE as text. Moving or renaming it means
+ * updating the test's path and regex, not just the import sites.
+ */
+export const CANONICAL_CONTENT_TYPES = ['user_voice', 'report_evidence', 'marketing_seo'];
+/**
+ * The four states, enumerated for a tool DESCRIPTION or a schema `.describe()`.
+ *
+ * A description is an executable interface: an agent reads it BEFORE its first call and is primed
+ * by it, so a trust qualifier that exists only in the rendered output is discoverable one call too
+ * late (FUL-341). Carries no leading clause — each surface supplies its own ("every thread carries
+ * a `source type:` line", "every receipt carries…") — and no trailing space.
+ */
+export const CONTENT_TYPE_STATES = '`user_voice` (a real person\'s first-hand account), `report_evidence` ' +
+    '(authoritative/third-person reporting), `marketing_seo` (vendor marketing or SEO content), or ' +
+    '`unclassified`.';
+/**
+ * The two exclusions, in the ONE wording every surface states them in.
+ *
+ * ⚠️ Both are real and both are enforced: `GROUNDING_ELIGIBLE_CONTENT_TYPES` (`community-db.ts`)
+ * is `CONTENT_TYPES` minus `FLAGGED_CONTENT_TYPES` since FUL-531, so neither kind reaches the
+ * automatic synthesis prompt, and `buildCommunityThemes` grounds no theme on either. They are
+ * still stated SEPARATELY because they do not mean the same thing — one source was classified and
+ * judged vendor copy, the other has not been looked at — and an agent that conflated them would
+ * treat an unexamined source as an examined one.
+ *
+ * ⚠️ FUL-560 extracted this from the two `registry.ts` adverts that already held it word-for-word
+ * by hand. The `get_report` receipt pools were the surface that had NO wording at all, and adding
+ * a fifth hand-copy to fix that is the drift FUL-247 exists to prevent — so the copies became one
+ * constant, pinned across every surface by `content-type-display.test.ts`. No leading or trailing
+ * space; each caller joins it.
+ */
+export const CONTENT_TYPE_EXCLUSIONS = '`marketing_seo` is shown for awareness but is EXCLUDED from grounding AND from automatic ' +
+    'community synthesis — it is vendor marketing or SEO content, never cite it as user ' +
+    'evidence. `unclassified` is EXCLUDED from both as well, and means the classification is ' +
+    'genuinely unknown, NOT that the source was checked and found benign.';
+/**
+ * FUL-560 — the receipt-pool paragraph, in the ONE wording every tool that RENDERS the trust digest
+ * advertises it in.
+ *
+ * `composeReportText` puts the same two receipt pools in the result text of `get_report`,
+ * `clien_research` and `clien_research_status`, so all three emit these `source type:` lines and all
+ * three must explain them: an agent that ran the hero tool and never calls `get_report` would
+ * otherwise meet the vocabulary for the first time in the output, which is the discoverable-one-call-
+ * too-late failure {@link CONTENT_TYPE_STATES} exists to avoid. Three hand-copies of a paragraph is
+ * also exactly the drift that made this module necessary — hence one constant, and
+ * `content-type-display.test.ts` DERIVES the tools that must carry it from the source rather than
+ * listing them, so a fourth digest surface fails the suite instead of shipping unadverted.
+ *
+ * Opens as a noun phrase so it can be a numbered item in `get_report`'s list or the object of a
+ * lead-in sentence elsewhere. No trailing space; each caller joins it.
+ */
+export const CONTENT_TYPE_DIGEST_ADVERT = 'the SOURCE TYPE on every receipt — ' +
+    CONTENT_TYPE_STATES +
+    ' Every "RRCP-" market/competitor receipt carries a `source type:` line; a "RCP-" persona receipt ' +
+    'is a first-hand `user_voice` post unless its row says otherwise, and any that is not carries the ' +
+    'same line marked \u26a0. ' +
+    CONTENT_TYPE_EXCLUSIONS;
+/**
+ * Normalize a persisted classification, failing CLOSED.
+ *
+ * Anything outside the canonical set — a typo'd literal, a value from a newer app version this
+ * client predates — becomes `null`, exactly like a missing one. A `!== null` check here instead
+ * would let an unrecognized string read as CLASSIFIED and present unvetted evidence to an agent as
+ * grounding-eligible. Version skew makes that a real case for a published client, not a
+ * hypothetical one.
+ *
+ * ⚠️ FUL-536 adds a second reason on the `search_forums` side. There the value is read out of a
+ * stored `report_data` document rather than a CHECK-constrained column, and `ForumThreadSchema` is
+ * `.passthrough()` — so a hallucinated `contentType: 'user_voice'` from an older run is a shape the
+ * parser accepts. `tagFastPathContentTypes` (FUL-535) deletes model-emitted types at the agent's
+ * read chokepoint for NEW data; this is what stops an old one being rendered as a classification.
+ */
+export function canonicalContentType(value) {
+    return typeof value === 'string' && CANONICAL_CONTENT_TYPES.includes(value)
+        ? value
+        : null;
+}
+/**
+ * The continuation-line indent every surface renders this on. One constant, so the two
+ * compositions below cannot drift apart by a space.
+ */
+const CONTINUATION = '\n   ';
+/**
+ * The sentence itself, without the indent — what a reader actually reads.
+ *
+ * Split out by FUL-560 purely so {@link contentTypeDeviationLine} can prefix a marker without
+ * restating any of the three branches. Nothing calls this directly; the exported line builders
+ * are the API, and holding the wording in ONE expression is the whole point of this module.
+ */
+function contentTypeSentence(value) {
+    const contentType = canonicalContentType(value);
+    return !contentType
+        ? 'source type: unclassified - excluded from grounding and community synthesis'
+        : contentType === 'marketing_seo'
+            ? 'source type: marketing_seo - vendor marketing, excluded from grounding and community synthesis'
+            : `source type: ${contentType}`;
+}
+/**
+ * The `source type:` continuation line, for a row rendered in the `\n   ` continuation shape both
+ * surfaces use. Never returns an empty string: see the both-directions rule above.
+ *
+ * Accepts the absent value in either spelling — `null` for a `community_signals` column, `undefined`
+ * for a `report_data` thread key FUL-535 deliberately left unstamped — because the two surfaces
+ * store "we don't know" differently and neither should have to widen its own types to say so.
+ */
+export function contentTypeProvenanceLine(value) {
+    return `${CONTINUATION}${contentTypeSentence(value)}`;
+}
+/**
+ * FUL-560 — the same sentence, marked as a DEVIATION from a pool's stated invariant.
+ *
+ * `get_report`'s PERSONA receipt pool is the one surface where the type is a near-constant rather
+ * than a per-row fact: `stampEvidenceMetadata` prunes every non-`user_voice` source out of
+ * `persona.sources` upstream, so a per-row line there would repeat one word down the whole pool
+ * and bury the row that broke the rule. The pool states the invariant once in its header and each
+ * row that does NOT satisfy it carries this line — which is the both-directions rule kept, not
+ * traded away: a reader is told the rule AND told, loudly, wherever it does not hold.
+ *
+ * ⚠️ The marker is emphasis, NOT vocabulary. It prefixes the shared sentence rather than replacing
+ * any of it, so the wording an agent matches on stays byte-identical to every other surface — the
+ * FUL-247 drift this module exists to prevent. A row whose type is absent or non-canonical is a
+ * deviation too: `user_voice` is a positive claim, and anything else is the caller failing closed.
+ */
+export function contentTypeDeviationLine(value) {
+    return `${CONTINUATION}\u26a0 ${contentTypeSentence(value)}`;
+}
+//# sourceMappingURL=content-type-display.js.map

package/dist/tools/content-type-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-type-display.js","sourceRoot":"","sources":["../../src/tools/content-type-display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,YAAY,EAAE,iBAAiB,EAAE,eAAe,CAAU,CAAA;AAElG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,wEAAwE;IACxE,gGAAgG;IAChG,iBAAiB,CAAA;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAClC,2FAA2F;IAC3F,qFAAqF;IACrF,0FAA0F;IAC1F,sEAAsE,CAAA;AAExE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,0BAA0B,GACrC,qCAAqC;IACrC,mBAAmB;IACnB,mGAAmG;IACnG,mGAAmG;IACnG,2BAA2B;IAC3B,uBAAuB,CAAA;AAEzB;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,uBAA6C,CAAC,QAAQ,CAAC,KAAK,CAAC;QAChG,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,CAAA;AACV,CAAC;AAED;;;GAGG;AACH,MAAM,YAAY,GAAG,OAAO,CAAA;AAE5B;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,MAAM,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAA;IAC/C,OAAO,CAAC,WAAW;QACjB,CAAC,CAAC,6EAA6E;QAC/E,CAAC,CAAC,WAAW,KAAK,eAAe;YAC/B,CAAC,CAAC,gGAAgG;YAClG,CAAC,CAAC,gBAAgB,WAAW,EAAE,CAAA;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,OAAO,GAAG,YAAY,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAA;AACvD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,GAAG,YAAY,UAAU,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAA;AAC9D,CAAC"}

package/dist/tools/interview-scripts.js

@@ -0,0 +1,360 @@
+/**
+ * `list_interview_scripts` (FUL-514) — the questions a run says are worth asking.
+ *
+ * Before this tool, MCP had the ACTION without the PLAN. An agent could call
+ * `interview_persona` but could not first read what the research decided was worth
+ * asking, so it either invented questions unanchored to the run's open hypotheses
+ * — in which case the answers cannot feed back into the claim spine — or
+ * re-derived them from `get_report`'s hypothesis list, which is the FUL-510
+ * failure again: an agent recomputing something the run already produced and
+ * stored. The web app has handed a human this screen for free since FUL-327.
+ *
+ * ⚠️ THIS TOOL NEVER GENERATES A SCRIPT. Scripts are the deterministic output of a
+ * research run (`agent/src/interview-script.ts`), written into the run's report
+ * and immutable thereafter. Deriving them on a miss would make a free read do
+ * model work and spend money on a GET, so a project with none gets the honest
+ * empty state and nothing else. The wording of that empty state matters as much as
+ * the guarantee: "no run has written scripts" is not "there is nothing worth
+ * asking".
+ *
+ * Contract:
+ *   - list_interview_scripts → GET /api/interview-scripts?projectId →
+ *       { interviewScripts: <script>[] | null, sourceRun: { id, createdAt } | null }
+ *
+ * ⚠️ VOCABULARY, and why this differs from `collections.ts`. The two collections
+ * and `get_market` read PROMOTED TABLES, so their endpoints return raw snake_case
+ * rows and those modules map at the tool boundary. Interview scripts are not a
+ * table — they live inside `validation_jobs.report_data.interviewScripts` — so
+ * `/api/interview-scripts` returns a shape the app has already mapped, ranked and
+ * joined to its hypotheses. The mapper below therefore NORMALISES (type-checks
+ * every field, degrades a bad one to null) rather than renames. It is still
+ * written out field by field, for the same reason the collection mappers are: the
+ * field list is part of the public MCP contract and must be readable in review.
+ *
+ * ⚠️ RANKING AND SELECTION ARE THE SERVER'S. Which run owns a project's scripts
+ * (`latestScriptedRunQuery` — newest non-scoped run that actually wrote an array)
+ * and what order they come in (`buildRankedScripts` — least-settled verdict first)
+ * are decided once, app-side, by the same functions the web screen renders from.
+ * Re-sorting here is what would let the two surfaces disagree about which
+ * hypothesis is most worth a real answer.
+ *
+ * Everything else follows its siblings: the shared `apiCall` client, the shared
+ * 401/404/400 mapping, and the rule that "I could not read the answer" and "the
+ * answer is none" must never look the same. Read-only, so a timeout is always safe
+ * to retry — no work lost, no credit spent.
+ */
+import { z } from 'zod';
+import { CollectionToolError, formatZodError, makeCtx, throwForResponse, } from './collections.js';
+import { apiCall } from './research.js';
+import { safeId, safeInline, truncate, collapseWhitespace } from './render-safety.js';
+const SCRIPTS_FETCH_TIMEOUT_MS = 30_000;
+export const ListInterviewScriptsInputSchema = z.object({
+    project_id: z
+        .string()
+        .uuid()
+        .describe('UUID of the project whose interview scripts to read. Get it from ' +
+        '`list_projects` (or `create_project`). Rejected with a 404 if you do not own the ' +
+        'project. Returns the STORED OUTPUT OF ONE SPECIFIC RESEARCH RUN — the scripts that ' +
+        'run wrote when it ran, one per hypothesis, ranked least-settled first — not a live ' +
+        'suggestion and not something generated when you call this. The run is named in the ' +
+        'result; pass its id to `get_report` for the hypotheses behind the questions. A ' +
+        'project can legitimately have NO scripts; that is reported as "no run has written ' +
+        'any", never as "there is nothing worth asking".'),
+});
+function asText(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+/**
+ * A 0–1 confidence, or null.
+ *
+ * Out-of-range and non-finite numbers become null rather than being printed. The
+ * app drops them for the same reason at its own render seam: a percentage derived
+ * from 999 reads as a measurement, and this tool has no way to caption it as
+ * nonsense in the one line it gets.
+ */
+function asFraction(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return null;
+    return value >= 0 && value <= 1 ? value : null;
+}
+export function toInterviewScriptEntry(row) {
+    return {
+        hypothesisId: asText(row.hypothesisId),
+        statement: asText(row.statement),
+        status: asText(row.status),
+        verdictLabel: asText(row.verdictLabel),
+        confidence: asFraction(row.confidence),
+        whoToAsk: asText(row.whoToAsk),
+        // A drifted null (or a string where an array belongs) costs the questions,
+        // never the script: the hypothesis it names is still worth reporting.
+        questions: Array.isArray(row.questions)
+            ? row.questions.filter((q) => typeof q === 'string')
+            : [],
+    };
+}
+export function toInterviewScriptsSourceRun(row) {
+    return { id: asText(row.id), createdAt: asText(row.createdAt) };
+}
+// ---------------------------------------------------------------------------
+// Render caps
+// ---------------------------------------------------------------------------
+/**
+ * Upper bound on scripts RENDERED, matching `report-digest.ts`'s `LIST_RENDER_CAP`
+ * for personas and hypotheses. A run writes one script per hypothesis and the
+ * producer's hypothesis cap is far below this, so it should never fire — but an
+ * unfired cap that would truncate silently is the thing this package refuses.
+ * When it fires it says so, and says where the rest are.
+ */
+const SCRIPT_RENDER_CAP = 25;
+/**
+ * Questions rendered per script. The generator writes exactly 3; the cap exists
+ * for a report written by some other build, and announces itself the same way.
+ */
+const QUESTION_RENDER_CAP = 12;
+const STATEMENT_MAX = 240;
+const WHO_TO_ASK_MAX = 240;
+const QUESTION_MAX = 300;
+const VERDICT_MAX = 40;
+const TIMESTAMP_MAX = 40;
+/**
+ * GET /api/interview-scripts for one project.
+ *
+ * ⚠️ THE NULL AND THE THROW ARE DIFFERENT ANSWERS, and the difference is decided by
+ * KEY PRESENCE, not truthiness. `{ "interviewScripts": null }` is the endpoint
+ * saying "no run has written scripts for this project" — a real, quotable fact. A
+ * 200 whose body has no `interviewScripts` key at all (an HTML error page from a
+ * proxy, a truncated response, a reshaped envelope) is the endpoint saying nothing,
+ * and must not arrive at an agent wearing the empty state's words: that empty state
+ * ends with "run `clien_research`", which DEBITS CREDITS. A transport failure read
+ * as "this project has no plan" can cost the user real money.
+ */
+async function fetchInterviewScripts(deps, projectId) {
+    const action = 'read the interview scripts';
+    const ctx = makeCtx(deps);
+    const query = new URLSearchParams({ projectId });
+    let response;
+    try {
+        response = await apiCall(ctx, 'GET', `/api/interview-scripts?${query.toString()}`, {
+            timeoutMs: SCRIPTS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new CollectionToolError(`Timed out after ${SCRIPTS_FETCH_TIMEOUT_MS / 1000}s trying to ${action}. ` +
+                'Try again in a moment — this is a read, so nothing was spent and nothing was lost.');
+        }
+        throw err;
+    }
+    if (!response.ok)
+        await throwForResponse(response, deps, action, projectId);
+    const json = (await response.json().catch(() => null));
+    const unreadable = new CollectionToolError(`Could not ${action} — the server returned a 200 with an unreadable body ` +
+        '(no `interviewScripts` key). This is NOT "the project has no interview scripts": the ' +
+        'request failed and scripts may well exist. Retry — this is a read, so nothing was spent ' +
+        'and nothing was lost. Do not tell anyone this project has no interview plan on the ' +
+        'strength of this, and do not start a paid research run because of it.');
+    if (json === null ||
+        typeof json !== 'object' ||
+        Array.isArray(json) ||
+        !('interviewScripts' in json)) {
+        throw unreadable;
+    }
+    const rawRun = json.sourceRun;
+    const sourceRun = rawRun !== null && typeof rawRun === 'object' && !Array.isArray(rawRun)
+        ? toInterviewScriptsSourceRun(rawRun)
+        : null;
+    const raw = json.interviewScripts;
+    if (raw === null)
+        return { scripts: null, sourceRun };
+    if (!Array.isArray(raw))
+        throw unreadable;
+    const scripts = raw
+        .filter((entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry))
+        .map(toInterviewScriptEntry);
+    return { scripts, sourceRun };
+}
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+/**
+ * The provenance sentence, in the TEXT channel because that is the one an agent
+ * always receives (FUL-243: `_meta` is a mirror, Claude Code drops it).
+ *
+ * A run id this client cannot state EXACTLY gets its own sentence rather than
+ * silence. Silence would read as "there is nothing to say about where these came
+ * from", when the truth is that the provenance is unknown — and a question set
+ * with unknown provenance is exactly the one an agent must not attribute to
+ * "the research".
+ */
+function provenanceLine(runId, createdAt) {
+    const safe = safeId(runId);
+    const when = safeInline(createdAt, TIMESTAMP_MAX);
+    if (!safe) {
+        return ('PROVENANCE: these scripts name NO source run — either the response omitted it or the ' +
+            'run behind them has since been deleted. Report them as recorded, never as "run X ' +
+            'recommends asking".');
+    }
+    return (`PROVENANCE: every script above was written by research run ${safe}` +
+        (when ? ` (recorded ${when})` : '') +
+        '. A report is an immutable snapshot, so the verdicts beside each question are that run\'s, ' +
+        `not today's — call \`get_report\` with job_id=${safe} for the hypotheses behind them.`);
+}
+/**
+ * The linkage instruction.
+ *
+ * ⚠️ Stated because nothing downstream enforces it: `interview_persona` takes no
+ * hypothesis id, so the tie between an answer and the hypothesis it tests exists
+ * only for as long as the CALLER carries `hypothesisId` forward. An agent that
+ * runs these questions and reports the answers without it has produced exactly the
+ * unanchored interview this tool was built to prevent.
+ */
+const LINKAGE_LINE = 'LINKAGE: each script names the `hypothesisId` it was written to test. Carry that id alongside ' +
+    'whatever the interview returns — `interview_persona` does not record it for you — or the ' +
+    'answers cannot be tied back to the hypothesis, which is the whole point of asking them.';
+/**
+ * The trust caveat.
+ *
+ * A verdict printed beside a question reads as settled unless something says
+ * otherwise (FUL-247). These verdicts are the run's reading of its own hypothesis,
+ * not the grading of a claim: the per-claim GROUNDED / SPECULATION / NO_RECEIPT
+ * states live in the source run's claim spine, which this separately released
+ * client cannot reconstruct.
+ */
+const SCRIPTS_TRUST_LINE = 'TRUST: the verdict and confidence on each script are the source run\'s reading of that ' +
+    'hypothesis, not a graded claim. Nothing here carries a GROUNDED / SPECULATION / NO_RECEIPT ' +
+    'state — read the source run with `get_report` for those. A high confidence is a reason to ask ' +
+    'a different question, never a reason to skip asking.';
+const CHANNEL_NOTE = 'The full record is in `structuredContent.interviewScripts` (also mirrored in `_meta`).';
+/** `Weak signal (inconclusive), confidence 52%` — or the honest partial forms. */
+function verdictClause(script) {
+    const label = safeInline(script.verdictLabel, VERDICT_MAX);
+    const status = safeInline(script.status, VERDICT_MAX);
+    const confidence = script.confidence === null ? null : `confidence ${Math.round(script.confidence * 100)}%`;
+    const verdict = label && status ? `${label} (${status})` : label ?? status ?? 'verdict not recorded';
+    return confidence ? `${verdict}, ${confidence}` : `${verdict}, confidence not recorded`;
+}
+/** The question list for one script, capped and — when capped — saying so. */
+function questionBlock(questions) {
+    const flat = questions
+        .map((q) => collapseWhitespace(typeof q === 'string' ? q : ''))
+        .filter((q) => q.length > 0);
+    // Branch on the RENDERED questions, not on `questions.length`: `['']` has
+    // length 1 and collapses to nothing, and a "Questions:" header over no
+    // questions reads as a rendering bug rather than as a script that lost them.
+    if (flat.length === 0) {
+        return '   Questions: none readable in the stored script.';
+    }
+    const shown = flat.slice(0, QUESTION_RENDER_CAP);
+    const lines = shown.map((q, i) => `     ${i + 1}. ${truncate(q, QUESTION_MAX)}`);
+    const dropped = flat.length - shown.length;
+    const more = dropped > 0
+        ? `\n     (${dropped} more in \`structuredContent.interviewScripts\`)`
+        : '';
+    return `   Questions:\n${lines.join('\n')}${more}`;
+}
+/** One ranked script as its own block. */
+function renderScript(script, rank) {
+    const id = safeId(script.hypothesisId);
+    const statement = safeInline(script.statement, STATEMENT_MAX);
+    const whoToAsk = safeInline(script.whoToAsk, WHO_TO_ASK_MAX);
+    // The heading names the hypothesis, because a question set detached from the
+    // hypothesis it serves is the thing this tool exists to stop being handed out.
+    const heading = statement
+        ? `${rank}. ${statement}`
+        : `${rank}. (this run recorded no statement for the hypothesis this script serves)`;
+    const lines = [
+        heading,
+        id
+            ? `   Hypothesis: ${id} — ${verdictClause(script)}`
+            : `   Hypothesis: NOT IDENTIFIED — ${verdictClause(script)}. Without an id these answers ` +
+                'cannot be tied back to a hypothesis.',
+    ];
+    if (whoToAsk)
+        lines.push(`   Who to ask: ${whoToAsk}`);
+    lines.push(questionBlock(script.questions));
+    return lines.join('\n');
+}
+export async function listInterviewScripts(input, deps) {
+    const parsed = ListInterviewScriptsInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new CollectionToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { project_id: projectId } = parsed.data;
+    const { scripts, sourceRun } = await fetchInterviewScripts(deps, projectId);
+    let text;
+    if (scripts === null) {
+        // ⚠️ THE HONEST EMPTY STATE. "Absent" is not "settled" and it is not "we looked
+        // and there was nothing worth asking". A scoped scan or a failed run leaves a
+        // project with no scripts while its hypotheses are wide open, so this sentence
+        // has to say that nothing is on record rather than imply a finding.
+        text =
+            `No interview scripts recorded for project ${projectId}.\n\n` +
+                'This means NO completed research run has written interview scripts for this project. It ' +
+                'is NOT a finding about the hypotheses: not "they are settled", not "there is nothing ' +
+                'worth asking", not zero. There is simply nothing on record.\n\n' +
+                'This tool never generates scripts — it reads what a run stored, and it will keep ' +
+                'returning this until one exists. Run `clien_research` (a full run) to produce them. ' +
+                '`scan_competitors` and `search_forums` are scoped runs and never write scripts, so ' +
+                'running those will leave this empty.';
+    }
+    else {
+        const runId = safeId(sourceRun?.id ?? null);
+        const when = safeInline(sourceRun?.createdAt ?? null, TIMESTAMP_MAX);
+        if (scripts.length === 0) {
+            // ⚠️ A DIFFERENT FACT FROM THE `null` BRANCH. A run IS on record and it did
+            // write a scripts array — the endpoint only names a run that did. Nothing in
+            // it could be read, which is a defect in the stored report, not a statement
+            // about the hypotheses. Collapsing the two would tell a caller no research
+            // has been done when some has.
+            text =
+                `Project ${projectId} has a research run that wrote interview scripts, and none of ` +
+                    'them could be read.\n\n' +
+                    (runId
+                        ? `Run ${runId}${when ? ` (recorded ${when})` : ''} stored a scripts array whose ` +
+                            'entries are unusable — a malformed report, not an answer about the hypotheses. '
+                        : 'The run that wrote them stored a scripts array whose entries are unusable — a ' +
+                            'malformed report, not an answer about the hypotheses. ') +
+                    'Do not treat this as "nothing worth asking". Read the run itself with `get_report` for ' +
+                    'its hypotheses, or run `clien_research` again to write a fresh set.\n\n' +
+                    provenanceLine(sourceRun?.id ?? null, sourceRun?.createdAt ?? null) +
+                    '\n\n' +
+                    CHANNEL_NOTE;
+        }
+        else {
+            const shown = scripts.slice(0, SCRIPT_RENDER_CAP);
+            const dropped = scripts.length - shown.length;
+            const capNote = dropped > 0
+                ? `\n\n(${dropped} more script${dropped === 1 ? '' : 's'} in ` +
+                    '`structuredContent.interviewScripts`.)'
+                : '';
+            text =
+                `Interview scripts for project ${projectId} — ${scripts.length} script` +
+                    `${scripts.length === 1 ? '' : 's'}` +
+                    `${runId ? ` from research run ${runId}` : ''}${when ? ` (recorded ${when})` : ''}.\n\n` +
+                    'These are the STORED output of that run, written when it ran. Nothing was generated to ' +
+                    'answer this call.\n\n' +
+                    'RANKED least-settled first: the hypothesis nearest a coin flip goes first, because a ' +
+                    'real answer there moves the verdict most. That order is the run\'s, not this ' +
+                    'client\'s.\n\n' +
+                    shown.map((script, i) => renderScript(script, i + 1)).join('\n\n') +
+                    capNote +
+                    '\n\n' +
+                    LINKAGE_LINE +
+                    '\n\n' +
+                    provenanceLine(sourceRun?.id ?? null, sourceRun?.createdAt ?? null) +
+                    '\n\n' +
+                    SCRIPTS_TRUST_LINE +
+                    '\n\n' +
+                    CHANNEL_NOTE;
+        }
+    }
+    return {
+        content: [{ type: 'text', text }],
+        // Both keys are present even when null — the PRESENCE is what tells a
+        // structured consumer "no run has written scripts" apart from "this tool did
+        // not answer".
+        _meta: { interviewScripts: scripts, sourceRun },
+    };
+}
+//# sourceMappingURL=interview-scripts.js.map

package/dist/tools/interview-scripts.js.map

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

package/dist/tools/interview.js

@@ -112,8 +112,8 @@ function makeCtx(deps) {
  * insufficient-credit stop with balance/required/buy-url guidance; 401 drops the
  * cached session (so the next tool call rebuilds from disk) and surfaces a
  * re-auth message; 404 means the interview/project isn't owned by the caller;
- * 400 surfaces the server's validation detail; everything else surfaces a
- * generic HTTP error.
+ * 403 with a lock code surfaces the upgrade path; 400 surfaces the server's
+ * validation detail; everything else surfaces a generic HTTP error.
  *
  * FUL-161: the body is read and parsed ONCE up front rather than after the 404
  * branch, because the 402 branch needs its `balance`/`required`/`buy_url` and a
@@ -159,6 +159,22 @@ async function throwForResponse(response, deps, action, options) {
             deps.invalidateSession?.();
         throw new InterviewToolError('Session expired. Re-run any Clien.ai tool to re-authenticate, then try again.');
     }
+    // FUL-503. Without this branch a subscription lock reads as
+    // `Failed to start interview (HTTP 403)` — indistinguishable from a bug, so the
+    // agent retries something no retry can fix. Mirrors `personas.ts`, including
+    // naming the resource that is actually locked.
+    //
+    // FUL-553 widened where these codes come from: `start` was the only action that
+    // could produce them, and now `turn` and `complete`/`reopen` do too, because a
+    // locked project is read-only IN FULL rather than merely uncreatable-in. The
+    // copy is already action-parameterised, so it needed no change — but note that
+    // a PROJECT_LOCKED on a `turn` refers to an interview that DOES exist and is
+    // simply frozen, unlike the same code on a `start`.
+    if (status === 403 && (parsed?.code === 'PROJECT_LOCKED' || parsed?.code === 'PERSONA_LOCKED')) {
+        throw new InterviewToolError(parsed.code === 'PROJECT_LOCKED'
+            ? `Could not ${action} — the project is locked due to subscription limits and is read-only. Upgrade to Pro to change it.`
+            : `Could not ${action} — the persona is locked due to subscription limits. Upgrade to Pro to interview it.`);
+    }
     if (status === 404) {
         throw new InterviewToolError(options?.notFound ??
             `Could not ${action} — interview or project not found, or you don't own it. ` +