@cotrrackpro-dev/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@cotrackpro/sdk` are documented here.
+
+## 0.1.0 - 2026-07-05
+
+Initial public release. Synced the catalog from the canonical
+`cotrackpro-antigravity` model and added two first-class entities plus the
+child-centered / trauma-informed taxonomy.
+
+### Reliability
+- **core/transport** — a per-request timeout (`timeoutMs`, default 30s, `0`
+  disables) via `AbortController`, so a hung connection can't hang a consumer;
+  surfaces as a retryable `network` error.
+- **auth/deviceFlow** — the login poll loop tolerates a transient error
+  (network/timeout/`5xx`) and keeps polling to the deadline, while a terminal
+  `4xx` still fails fast.
+- **nocode/validate** — `validateApp`/`appWarnings` guard a malformed app
+  (missing `nodes`/`variables`/`edges`/`settings`) instead of throwing a raw
+  `TypeError`.
+- **params/convert** — `schemaToFields` rejects a non-object property value with a
+  clear error instead of a raw `TypeError`.
+
+### Catalog + entities
+- **mcp** — new generated registries: `SKILLS`/`SKILL_NAMES` (33) and
+  `KNOWLEDGE`/`KNOWLEDGE_NAMES` (5). Enriched existing registries: `WORKFLOWS`
+  carry `version`/`trigger`/`condition`/`safetyLevel`/`steps` (the real step
+  graph), `ROLES` carry `composes`/`promptModules`/`safetyLevel`/`chainsWith`,
+  `ARTIFACTS` carry `safetyFields`/`hasProvenance`/`safetyRelevant`, prompt
+  modules carry `knowledgeRefs`.
+- **mcp/safety** — `safetyTagsFor`, `isChildCentered`, `isTraumaInformed`,
+  `roleIdsWithTag`, `skillNamesWithTag`, `knowledgeForModules`,
+  `guardrailModulesForWorkflow`; `GuardrailTag`/`SafetyLevel` types.
+- **mcp/format** — `describeWorkflowStep`, `workflowWalkthrough`.
+- **mcp** — `CotrackproToolset` gains `listSkills`, `listKnowledge`, `getWorkflow`.
+- **guide** — `GuideWorkflowRef` gains `safetyLevel`/`walkthrough`; new
+  `GuideKnowledgeRef` + `GuideInput.knowledge`; the renderer emits a workflow
+  step graph and a background-knowledge section.
+- **nocode** — new guardrail-aware starter app `coparent-message-rewrite`
+  (calls the `cotrackpro` MCP `rewrite_coparent_message` tool).
+
+### Foundations
+- **core** — `Transport` (fetch + retry/backoff + timeout, `x-request-id` capture,
+  uniform error model), `resolveSdkConfig`, framework-agnostic `CotrackproError`.
+- **auth** — pluggable `AuthProvider`: `StaticTokenProvider`, `CallbackTokenProvider`,
+  `DeviceFlowProvider`, `AnonymousProvider`.
+- **resources** — `createClient()` with typed `whoami`, `orgs`, `packages`, `auth`, `health`.
+- **mcp** — `CotrackproToolset` plus generated, offline, typed registries:
+  artifacts (133), roles (18), workflows (5), scenarios (9), prompt modules (12);
+  `searchArtifactsLocal` fuzzy search.
+- Ships built `dist` (ESM + `.d.ts`); runtime-agnostic (Node, edge, browser, agent hosts).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doug Devitre / CoTrackPro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @cotrackpro/sdk
+
+The typed TypeScript client for the CoTrackPro platform. One place for transport,
+auth, typed API resources, and MCP/artifact bindings — consumed by the CLI and
+every `cotrackpro*` repo, and built to be lifted into `cotrackpro-foundations`
+and published.
+
+## Why this exists
+
+Before the SDK, each repo (and the CLI) hand-rolled `fetch`, bearer auth,
+org-scoping, retries, and an ad-hoc error model. The SDK collapses that into a
+single, well-tested surface that runs anywhere `fetch` exists — Node, edge,
+browser, and agent/IDE hosts such as Google Antigravity.
+
+## Quick start
+
+```ts
+import { createClient, StaticTokenProvider } from "@cotrackpro/sdk";
+
+const cp = createClient({
+  baseUrl: "https://api.cotrackpro.com",
+  org: "acme",
+  auth: new StaticTokenProvider(process.env.COTRACKPRO_TOKEN!),
+});
+
+const me = await cp.whoami();
+const orgs = await cp.orgs.list();
+const pkgs = await cp.packages.list();
+```
+
+## Auth providers
+
+Pick the provider that matches your runtime — the rest of the SDK is identical:
+
+| Provider | Use case |
+| --- | --- |
+| `StaticTokenProvider` | API keys / env tokens — CI, agents, Antigravity |
+| `CallbackTokenProvider` | Read a token lazily from a keychain / store (the CLI) |
+| `DeviceFlowProvider` | Browser device-flow sign-in (CLI, desktop, IDE) |
+| `AnonymousProvider` | Unauthenticated endpoints (health, device start) |
+
+## MCP / artifacts
+
+`@cotrackpro/sdk/mcp` exposes typed bindings over the CoTrackPro MCP server plus
+a generated registry of all platform artifacts:
+
+```ts
+import {
+  ARTIFACTS, ARTIFACT_NAMES, type ArtifactName,
+  ROLES, WORKFLOWS, SCENARIOS, PROMPT_MODULES,
+  searchArtifactsLocal, CotrackproToolset,
+} from "@cotrackpro/sdk/mcp";
+
+ARTIFACTS["parenting-plan-draft"].dataSensitivity; // "confidential"
+ROLES["cotrackpro-judge"].airtableRoleNames;       // ["Judge", ...]
+searchArtifactsLocal("incident");                  // offline fuzzy search, ranked
+
+// In an MCP-capable host (Claude runtime, Antigravity), pass a tool-call fn:
+const cp = new CotrackproToolset((name, args) => host.callTool(`cotrackpro.${name}`, args));
+const artifacts = await cp.listArtifacts();
+```
+
+Offline, typed, generated registries (no network/auth): `ARTIFACTS` (133),
+`ROLES` (18), `WORKFLOWS` (5), `SCENARIOS` (9), `PROMPT_MODULES` (12) — each with an
+id union, a `Record<Id, Meta>`, and an ids array. `searchArtifactsLocal` ranks
+matches over the artifact registry.
+
+### Regenerating artifact types
+
+The registries are generated from snapshots of the MCP catalog
+(`schemas/*.index.json`, synced via the MCP `list_*` tools):
+
+```bash
+npm run codegen   # artifacts + roles/workflows/scenarios/prompt-modules -> src/mcp/*.generated.ts
+```
+
+To also generate field-level interfaces, drop per-artifact JSON Schemas (from the
+MCP `get_artifact_schema` tool) into `schemas/full/<name>.json` and re-run codegen.
+
+## Custom parameter sets (`@cotrackpro/sdk/params`)
+
+User-authored **parameter sets** — custom typed field schemas — share one source of truth
+across the CLI (`cotrackpro params`) and the portal builder:
+
+```ts
+import { fieldsToSchema, validateValues, renderMarkdown, type ParamSet } from "@cotrackpro/sdk/params";
+
+const set: ParamSet = { title: "Incident", dataSensitivity: "confidential", fields: [/* ... */] };
+const schema = fieldsToSchema(set);                 // canonical JSON Schema (Draft 2020-12)
+const { valid, errors } = validateValues(set, vals); // value validation (no ajv)
+const doc = renderMarkdown(set, vals);              // filled markdown document
+```
+
+The module's **core is import-free** (no `node:`/external deps) so its compiled output loads
+directly in the browser — the portal builder imports the very same `convert`/`validate`/`render`
+logic. `FIELD_TYPES`/`FIELD_TYPE_LIST` is the single declarative registry that drives the
+converter, both validators, the renderer, and the builder's widgets. `schemaToInterface`
+(Node-only, in `params/codegen.ts`) compiles a set to a TypeScript interface and is shared with
+`scripts/gen-artifacts.ts`.
+
+> The parameter-set format is intentionally **the same shared shape** the CoTrackPro
+> Intervention Builder uses to author items/templates — one format, two entry points (offline
+> CLI/portal convenience vs. the Builder's governed authoring path). See
+> [`../docs/strategy/three-surfaces.md`](../docs/strategy/three-surfaces.md) for the rationale
+> and the producer→contract→consumer model.
+
+## Testing
+
+```bash
+npm test          # from the repo root — runs the SDK unit tests via vitest
+```

package/dist/assistant/compliance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Compliance guard — Build Buddy is a build *copilot*, never an advice service. This is
+ * the coded line (not just a disclaimer) that keeps it from giving legal, medical, or
+ * mental-health advice. Dependency-free and shared by every surface (web + Slack).
+ *
+ * Posture (decided): block advice *applied to the user's own situation*, but still answer
+ * general/building questions. A disclaimer alone is not a defense (UPL law), so the broker
+ * short-circuits on a match BEFORE calling the model — same shape as crisis detection.
+ *
+ * NOTE: the refusal copy + the patterns below are pending review by a licensed attorney
+ * and a clinician before live answers are enabled (see the proposal's launch gate).
+ */
+export type AdviceDomain = "legal" | "medical" | "mental-health";
+export interface AdviceMatch {
+    matched: boolean;
+    domain?: AdviceDomain;
+}
+/** Detect a request for advice applied to the user's situation. Conservative by design. */
+export declare function detectAdviceRequest(text: string): AdviceMatch;
+/**
+ * The scoped, non-advice response. Acknowledges, declines the advice, routes to a
+ * licensed professional, and keeps the door open for build help. (Copy pending SME review.)
+ */
+export declare function adviceRefusal(domain: AdviceDomain, joinUrl?: string): string;

package/dist/assistant/compliance.js

@@ -0,0 +1,60 @@
+/**
+ * Compliance guard — Build Buddy is a build *copilot*, never an advice service. This is
+ * the coded line (not just a disclaimer) that keeps it from giving legal, medical, or
+ * mental-health advice. Dependency-free and shared by every surface (web + Slack).
+ *
+ * Posture (decided): block advice *applied to the user's own situation*, but still answer
+ * general/building questions. A disclaimer alone is not a defense (UPL law), so the broker
+ * short-circuits on a match BEFORE calling the model — same shape as crisis detection.
+ *
+ * NOTE: the refusal copy + the patterns below are pending review by a licensed attorney
+ * and a clinician before live answers are enabled (see the proposal's launch gate).
+ */
+// Each domain matches advice *applied to the user's situation* — not mere topic mentions.
+// "what artifacts document a custody incident" (building) must NOT match; "should I file
+// for custody" (advice) must.
+const PATTERNS = [
+    {
+        domain: "medical",
+        re: /\b(what('?s| is) wrong with (me|my)|should i (take|stop|change) (this )?(med|medication|drug|dose)|what (medication|dose|drug|meds) (should|do) i|diagnos(e|is|ing) (me|my)|is (this|that) (a )?(symptom|condition|disease)|do i have (a )?(condition|disorder|disease)|treat(ment)? for my)\b/i,
+    },
+    {
+        domain: "legal",
+        re: /\b(should i (file|sue|settle|sign|appeal|petition|respond)|do i have a (case|claim)|what are my (legal )?rights|is (this|that|it) (legal|illegal|admissible|enforceable)|can i (sue|file|get custody|win)|will i (win|lose|get custody)|how do i (file|serve|appeal|get a restraining order)|is (this|that) (abuse|neglect|contempt|grounds)|what should i (say|do) (in|at) court)\b/i,
+    },
+    {
+        domain: "mental-health",
+        re: /\b(am i (depressed|bipolar|anxious|traumatized|ok|crazy|a narcissist)|do i have (ptsd|depression|anxiety|adhd|a disorder)|is my (ex|partner|child|co-?parent) (a narcissist|bipolar|abusive|gaslighting)|should i (be on|take) (medication|antidepressants|therapy)|diagnose (me|my))\b/i,
+    },
+];
+/** Detect a request for advice applied to the user's situation. Conservative by design. */
+export function detectAdviceRequest(text) {
+    const t = (text || "").toLowerCase();
+    for (const { domain, re } of PATTERNS) {
+        if (re.test(t))
+            return { matched: true, domain };
+    }
+    return { matched: false };
+}
+const DOMAIN_LABEL = {
+    legal: "legal",
+    medical: "medical",
+    "mental-health": "mental-health",
+};
+const DOMAIN_ROUTE = {
+    legal: "a licensed attorney or your local legal-aid office",
+    medical: "a licensed medical professional",
+    "mental-health": "a licensed mental-health professional",
+};
+/**
+ * The scoped, non-advice response. Acknowledges, declines the advice, routes to a
+ * licensed professional, and keeps the door open for build help. (Copy pending SME review.)
+ */
+export function adviceRefusal(domain, joinUrl) {
+    const help = joinUrl ? ` If you're building a tool for this, I'm glad to help with that — see ${joinUrl}.` : " I'm glad to help with building a tool, though.";
+    return (`I can't give ${DOMAIN_LABEL[domain]} advice — I'm a build assistant, not a substitute ` +
+        `for a professional, and that's a decision for ${DOMAIN_ROUTE[domain]} who knows your ` +
+        `situation. I can share general, educational information and point you to the right ` +
+        `resources.${help}`);
+}
+//# sourceMappingURL=compliance.js.map

package/dist/assistant/compliance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compliance.js","sourceRoot":"","sources":["../../src/assistant/compliance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,0FAA0F;AAC1F,yFAAyF;AACzF,8BAA8B;AAC9B,MAAM,QAAQ,GAA2C;IACvD;QACE,MAAM,EAAE,SAAS;QACjB,EAAE,EAAE,iSAAiS;KACtS;IACD;QACE,MAAM,EAAE,OAAO;QACf,EAAE,EAAE,uXAAuX;KAC5X;IACD;QACE,MAAM,EAAE,eAAe;QACvB,EAAE,EAAE,0RAA0R;KAC/R;CACF,CAAC;AAEF,2FAA2F;AAC3F,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACrC,KAAK,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,QAAQ,EAAE,CAAC;QACtC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,YAAY,GAAiC;IACjD,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,eAAe,EAAE,eAAe;CACjC,CAAC;AAEF,MAAM,YAAY,GAAiC;IACjD,KAAK,EAAE,oDAAoD;IAC3D,OAAO,EAAE,iCAAiC;IAC1C,eAAe,EAAE,uCAAuC;CACzD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAoB,EAAE,OAAgB;IAClE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,yEAAyE,OAAO,GAAG,CAAC,CAAC,CAAC,iDAAiD,CAAC;IAC/J,OAAO,CACL,gBAAgB,YAAY,CAAC,MAAM,CAAC,oDAAoD;QACxF,iDAAiD,YAAY,CAAC,MAAM,CAAC,kBAAkB;QACvF,qFAAqF;QACrF,aAAa,IAAI,EAAE,CACpB,CAAC;AACJ,CAAC"}

package/dist/assistant/crisis.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Crisis detection — the hard-wired safety net shared by every assistant surface
+ * (the web widget AND the broker). Dependency-free on purpose so it ships to the
+ * browser as-is (copied by the site builder) and runs server-side unchanged.
+ *
+ * This is NOT a clinical triage tool. It errs toward surfacing help: if the text
+ * looks like crisis, the caller MUST lead with resources before any other action.
+ * Resources are never gated behind a question.
+ */
+export interface CrisisResource {
+    label: string;
+    /** Phone number (digits only) for a tel: link. */
+    tel?: string;
+    /** SMS instruction, e.g. "Text HOME to 741741". */
+    sms?: string;
+    note: string;
+}
+/** The canonical resource list — same numbers the crisis modal + MCP server use. */
+export declare const CRISIS_RESOURCES: readonly CrisisResource[];
+export type CrisisCategory = "suicidal" | "violence" | "child-safety" | "general";
+export interface CrisisMatch {
+    matched: boolean;
+    category?: CrisisCategory;
+    /** Resources ordered for the matched category (most relevant first). */
+    resources: readonly CrisisResource[];
+}
+/**
+ * Scan free text for crisis signals. Returns the matched category (if any) and
+ * the resources to surface. On no match, `matched:false` with an empty list.
+ */
+export declare function detectCrisis(text: string): CrisisMatch;

package/dist/assistant/crisis.js

@@ -0,0 +1,62 @@
+/**
+ * Crisis detection — the hard-wired safety net shared by every assistant surface
+ * (the web widget AND the broker). Dependency-free on purpose so it ships to the
+ * browser as-is (copied by the site builder) and runs server-side unchanged.
+ *
+ * This is NOT a clinical triage tool. It errs toward surfacing help: if the text
+ * looks like crisis, the caller MUST lead with resources before any other action.
+ * Resources are never gated behind a question.
+ */
+/** The canonical resource list — same numbers the crisis modal + MCP server use. */
+export const CRISIS_RESOURCES = [
+    { label: "911", tel: "911", note: "Immediate physical danger" },
+    { label: "988 Suicide & Crisis Lifeline", tel: "988", note: "Call or text, US, 24/7" },
+    { label: "Crisis Text Line", sms: "Text HOME to 741741", note: "Free, 24/7, confidential" },
+    { label: "National Domestic Violence Hotline", tel: "18007997233", note: "1-800-799-7233, 24/7" },
+    { label: "Childhelp National Child Abuse Hotline", tel: "18004224453", note: "1-800-422-4453" },
+];
+const PATTERNS = [
+    {
+        category: "suicidal",
+        re: /\b(kill myself|killing myself|end my life|ending my life|take my (own )?life|want to die|wanna die|don'?t want to (live|be here|be alive)|suicid|hurt myself|harm myself|no reason to live|better off dead)/i,
+    },
+    {
+        category: "child-safety",
+        re: /\b(child (abuse|is in danger|being hurt|being abused)|hurt(ing)? (my|the|a) (kid|child|son|daughter|baby)|abus(e|ing) (my|the|a) (kid|child)|my (kid|child) (is|isn'?t) safe)\b/i,
+    },
+    {
+        category: "violence",
+        re: /(\b(he|she|they|my (partner|ex|husband|wife)) (hit|hits|beat|beats|strangl|chok|threaten|threatened|attack))|domestic (violence|abuse)|being (abused|beaten|stalked|followed)|afraid (for|of) my (life|safety)|not safe at home|going to (hurt|kill) me/i,
+    },
+];
+/**
+ * Scan free text for crisis signals. Returns the matched category (if any) and
+ * the resources to surface. On no match, `matched:false` with an empty list.
+ */
+export function detectCrisis(text) {
+    const t = (text || "").toLowerCase();
+    for (const { category, re } of PATTERNS) {
+        if (re.test(t))
+            return { matched: true, category, resources: orderFor(category) };
+    }
+    return { matched: false, resources: [] };
+}
+/** Order the canonical resources so the most relevant line leads for a category. */
+function orderFor(category) {
+    const by = (label) => CRISIS_RESOURCES.find((r) => r.label.startsWith(label));
+    const pick = (...labels) => labels.map(by).filter((r) => Boolean(r));
+    switch (category) {
+        case "suicidal":
+            return [...pick("988", "Crisis Text Line", "911"), ...rest(["988", "Crisis Text Line", "911"])];
+        case "violence":
+            return [...pick("National Domestic Violence", "911", "988"), ...rest(["National Domestic Violence", "911", "988"])];
+        case "child-safety":
+            return [...pick("Childhelp", "911", "988"), ...rest(["Childhelp", "911", "988"])];
+        default:
+            return CRISIS_RESOURCES;
+    }
+}
+function rest(leadPrefixes) {
+    return CRISIS_RESOURCES.filter((r) => !leadPrefixes.some((p) => r.label.startsWith(p)));
+}
+//# sourceMappingURL=crisis.js.map

package/dist/assistant/crisis.js.map

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

package/dist/assistant/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @cotrackpro/sdk/assistant — the shared "assistant-core" reused by the web widget
+ * and the broker: crisis detection, RBAC tier→tool allowlist, and the guardrail
+ * system-prompt composer. Single source of truth so both surfaces enforce the same
+ * child-centered, trauma-informed contract.
+ *
+ * Note: `crisis` and `rbac` are dependency-free and browser-safe; `prompt` imports
+ * the catalog taxonomy and is server-only.
+ */
+export * from "./crisis.js";
+export * from "./rbac.js";
+export * from "./prompt.js";
+export * from "./levels.js";
+export * from "./readability.js";
+export * from "./compliance.js";

package/dist/assistant/index.js

@@ -0,0 +1,16 @@
+/**
+ * @cotrackpro/sdk/assistant — the shared "assistant-core" reused by the web widget
+ * and the broker: crisis detection, RBAC tier→tool allowlist, and the guardrail
+ * system-prompt composer. Single source of truth so both surfaces enforce the same
+ * child-centered, trauma-informed contract.
+ *
+ * Note: `crisis` and `rbac` are dependency-free and browser-safe; `prompt` imports
+ * the catalog taxonomy and is server-only.
+ */
+export * from "./crisis.js";
+export * from "./rbac.js";
+export * from "./prompt.js";
+export * from "./levels.js";
+export * from "./readability.js";
+export * from "./compliance.js";
+//# sourceMappingURL=index.js.map

package/dist/assistant/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/assistant/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/dist/assistant/levels.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Reading-level / age translator bands. People reach this platform under stress and
+ * at very different literacy levels — a child, a parent mid-crisis, a professional.
+ * A `ReadingLevel` maps to a target US school grade and a prompt directive that tells
+ * the model how to write. The substance (and crisis resources) never change — only
+ * the wording. Pair with `readability.ts` to verify the output actually hit the band.
+ */
+export type ReadingLevel = "kid" | "preteen" | "teen" | "plain" | "pro";
+export interface ReadingBand {
+    id: ReadingLevel;
+    label: string;
+    /** Target Flesch–Kincaid grade, or null for "professional" (unconstrained). */
+    grade: number | null;
+}
+/** The selectable bands, in order. "plain" is the portal's existing default. */
+export declare const READING_BANDS: readonly ReadingBand[];
+export declare const DEFAULT_READING_LEVEL: ReadingLevel;
+/** Coerce arbitrary input to a known level (defaults to "plain"). */
+export declare function asReadingLevel(v: unknown): ReadingLevel;
+/**
+ * Detect a reading-level request phrased in natural language (for surfaces without a
+ * selector, e.g. the Slack agent: "explain for a 10-year-old", "in plain English").
+ * Returns undefined when there's no hint.
+ */
+export declare function detectReadingLevel(text: string): ReadingLevel | undefined;
+/** Target grade for a level (null = professional / unconstrained). */
+export declare function targetGradeFor(level: ReadingLevel): number | null;
+/**
+ * The system-prompt directive for a level. For graded levels it constrains wording
+ * but explicitly preserves safety meaning + crisis resources; "pro" allows precise
+ * terminology. "plain" returns "" — it's the baseline the prompt already targets.
+ */
+export declare function readingLevelDirective(level: ReadingLevel): string;
+/** Ordered band ids, simplest → most technical. */
+export declare const LEVEL_ORDER: readonly ReadingLevel[];
+/** The next, more-technical level (or the same when already at the top). */
+export declare function nextLevel(level: ReadingLevel): ReadingLevel;
+/** The previous, simpler level (or the same when already at the bottom). */
+export declare function prevLevel(level: ReadingLevel): ReadingLevel;
+/** True when there's a more-technical level to grow into. */
+export declare function canLevelUp(level: ReadingLevel): boolean;
+/** Human label for a level id. */
+export declare function levelLabel(level: ReadingLevel): string;

package/dist/assistant/levels.js

@@ -0,0 +1,102 @@
+/** The selectable bands, in order. "plain" is the portal's existing default. */
+export const READING_BANDS = [
+    { id: "kid", label: "Kid", grade: 3 },
+    { id: "preteen", label: "Pre-teen", grade: 5 },
+    { id: "teen", label: "Teen", grade: 7 },
+    { id: "plain", label: "Plain", grade: 8 },
+    { id: "pro", label: "Professional", grade: null },
+];
+const BY_ID = Object.fromEntries(READING_BANDS.map((b) => [b.id, b]));
+export const DEFAULT_READING_LEVEL = "plain";
+/** Coerce arbitrary input to a known level (defaults to "plain"). */
+export function asReadingLevel(v) {
+    return typeof v === "string" && v in BY_ID ? v : DEFAULT_READING_LEVEL;
+}
+/** Map a US grade number to the nearest band. */
+function bandForGrade(grade) {
+    if (grade <= 3)
+        return "kid";
+    if (grade <= 5)
+        return "preteen";
+    if (grade <= 7)
+        return "teen";
+    return "plain";
+}
+/**
+ * Detect a reading-level request phrased in natural language (for surfaces without a
+ * selector, e.g. the Slack agent: "explain for a 10-year-old", "in plain English").
+ * Returns undefined when there's no hint.
+ */
+export function detectReadingLevel(text) {
+    const t = (text || "").toLowerCase();
+    const gradeM = t.match(/\bgrade[- ]?(\d{1,2})\b/) || t.match(/\b(\d{1,2})(?:st|nd|rd|th)[- ]?grade\b/);
+    if (gradeM)
+        return bandForGrade(Number(gradeM[1]));
+    const ageM = t.match(/\b(?:i'?m|i am|like i'?m|for a|for an|year[- ]?old|aged?)\D{0,12}?(\d{1,2})\b/);
+    if (ageM && /year|old|i'?m|i am|aged?|for a/.test(t)) {
+        const age = Number(ageM[1]);
+        if (age <= 8)
+            return "kid";
+        if (age <= 11)
+            return "preteen";
+        if (age <= 17)
+            return "teen";
+    }
+    if (/\b(for|like)\b.{0,12}\b(kid|child|young child|little (kid|one))\b/.test(t))
+        return "kid";
+    if (/\b(pre-?teen|tween)\b/.test(t))
+        return "preteen";
+    if (/\b(teen|teenager|high ?school)\b/.test(t))
+        return "teen";
+    if (/\b(plain|simple) (english|language|terms|words)\b|\bsimply\b|\bin plain\b/.test(t))
+        return "plain";
+    if (/\b(lawyer|attorney|professional|clinician|technical|be precise|precise terms)\b/.test(t))
+        return "pro";
+    return undefined;
+}
+/** Target grade for a level (null = professional / unconstrained). */
+export function targetGradeFor(level) {
+    return BY_ID[level]?.grade ?? null;
+}
+/**
+ * The system-prompt directive for a level. For graded levels it constrains wording
+ * but explicitly preserves safety meaning + crisis resources; "pro" allows precise
+ * terminology. "plain" returns "" — it's the baseline the prompt already targets.
+ */
+export function readingLevelDirective(level) {
+    if (level === "plain")
+        return "";
+    if (level === "pro") {
+        return "Audience: professionals (attorneys, GALs, clinicians). Precise legal and clinical terminology is fine; be exact and concise.";
+    }
+    const grade = targetGradeFor(level);
+    return [
+        `Write at a US grade-${grade} reading level: short sentences (mostly under 12 words)`,
+        `and everyday words. This reader is LEARNING the technical material, so teach as you go:`,
+        `explain each idea in plain words first, then introduce the correct technical term in`,
+        `parentheses (e.g. "a saved record (an 'artifact')") so their vocabulary grows and they`,
+        `can level up. Keep ALL safety meaning intact and reproduce any crisis resources exactly`,
+        `— never simplify those away. Change the wording, never the meaning.`,
+    ].join(" ");
+}
+/** Ordered band ids, simplest → most technical. */
+export const LEVEL_ORDER = READING_BANDS.map((b) => b.id);
+/** The next, more-technical level (or the same when already at the top). */
+export function nextLevel(level) {
+    const i = LEVEL_ORDER.indexOf(level);
+    return (i >= 0 ? LEVEL_ORDER[i + 1] : undefined) ?? level;
+}
+/** The previous, simpler level (or the same when already at the bottom). */
+export function prevLevel(level) {
+    const i = LEVEL_ORDER.indexOf(level);
+    return (i > 0 ? LEVEL_ORDER[i - 1] : undefined) ?? level;
+}
+/** True when there's a more-technical level to grow into. */
+export function canLevelUp(level) {
+    return level !== LEVEL_ORDER[LEVEL_ORDER.length - 1];
+}
+/** Human label for a level id. */
+export function levelLabel(level) {
+    return BY_ID[level]?.label ?? level;
+}
+//# sourceMappingURL=levels.js.map

package/dist/assistant/levels.js.map

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

package/dist/assistant/prompt.d.ts

@@ -0,0 +1,20 @@
+import type { AssistantTier } from "./rbac.js";
+import { type ReadingLevel } from "./levels.js";
+export interface SystemPromptOptions {
+    tier: AssistantTier;
+    /** The portal page the user is on, for context-aware help (e.g. "catalog"). */
+    page?: string;
+    /** Tool names the broker will actually expose this turn (from the allowlist). */
+    allowedTools: readonly string[];
+    /** Target reading level for the answer (the age/grade translator). */
+    readingLevel?: ReadingLevel;
+    /**
+     * What the turn is for. "ask" (default) is the normal Q&A copilot. "rewrite" re-tones
+     * a page's existing copy to the reading level without changing its meaning — the broker
+     * passes the page text as the user turn. The guardrails (crisis-first, advice-refusal,
+     * the child-centered lens) are identical for both.
+     */
+    intent?: "ask" | "rewrite";
+}
+/** Build the full system prompt for one turn, grounded in the live guardrails. */
+export declare function buildSystemPrompt(opts: SystemPromptOptions): string;