mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path > - Paperclip manages AI agents and their work. > - The experimental Runner owns provider processes and durable sessions. > - Pi needs working task execution and human controls. > - The five-PR stack must preserve changes already on master. > - Each layer now carries the complete integrated source for a safe sequential fallback. > - This PR belongs to native GitHub stack #15602, ending at #14956. ## Linked Issues or Issue Description Refs #14436, #14631, #14743 and #14956. Ship Pi 1.0 through the experimental Paperclip Runner. The five PRs are #14921, #14922, #14923, #14924 and #14956. The user authorized the complete merge after checks pass. Existing `pi_local` execution is unchanged. Accounting and wider provider/platform qualification remain deferred. ## What Changed - Recover missing final replies after workspace finalization changes owners, using accepted-turn evidence without rerunning work or granting external-chat publication. - Preserve the admitted Pi instruction root across warm runs, while retaining changed-root rejection. - Give Pi a bounded 15-second default shutdown grace so stop, drain acknowledgement and durable suspension can complete. Explicit deadlines and other providers retain their existing behavior. - Integrate the Pi 1.0 runtime and master contracts. - Use Pi profile 22. Preserve explicit caller-selected models and exact native thinking levels. Keep Pi's wrapper, helper, extension and question/control behavior unchanged from the qualified profile-19 runtime. - Preserve master's Dot lifecycle and consent fields, configured task environment, status guards and current Codex/Claude dependency versions. Cursor stays qualified. Copilot stays pending; profile 17 binds the changed shared protocol validation sources. - Exclude general AWS IAM credentials from Pi static/custom provider bindings and selected task projections; preserve the provider-scoped Bedrock bearer key. Profile 21 is retained as historical provenance. Rust and cloud install probes use the current declaration. - Patch bundled brace-expansion 5.0.9 to the exact official 5.0.12 payload. Pin the patch and complete runtime closures. Include the patch in normal installed setup tooling. Keep the upstream Pi shrinkwrap as provenance and permit only this exact security correction. - Include current attestation files in the Docker build context. Keep the repository lockfile unchanged from master. CI and private image builds resolve manifest changes before their frozen installation. ## Verification - Full local `pnpm -r typecheck` passes, including Runner Rust, server and UI. Focused integration checks pass: 194 Runner admission/environment tests, 63 profile/credential tests with one expected skip, 152 Dot/UI configuration tests, and Pi transcript/notice tests. - Full local `pnpm build` passes on the final source. - Fresh final-source checks pass: all 698 Rust workspace tests (32 binaries), 156 credential/profile/controller tests with one expected skip, Runner TypeScript typecheck, and 20 package/setup/sandbox tests. - The profile-21 Pi materializer passes on the native host with the official pinned Node 24.21.0 and its npm. It verifies all 150 locked packages, the patched dependency and the exact closure. Setup/package bundle tests and UI token gates pass. - The old hashes were reproduced for all three supported targets before calculating the patched graph. New closure hashes are darwin-arm64 `282022db10150c6632b3444df421342e7d534bdf5d5fb1097a2e79d0625a2bcf`, darwin-x64 `64e251e19009f755c0b04f73ce2138246faab71a961b0f13d75ebfcc34bef12e`, and linux-x64 `713b1fdff42fb56a1518bdc084f181d70bee8ebadc3e4b1d76321ed9108c8410`. Independent native platform execution is separate from graph identity reproduction. - Historical cloud qualification remains unchanged: all seven core cases pass on shipping source `10dc43c9ec65d88c2f782d62afb296d09494f215`, harness `1a4408a48cfb5a1f094a311141c257c92cd7a893`, image `sha256:5b3a775b383591bda1b0c1889e509acc70ce7f37c53f09733c81d59037f02280`, and accepted Sonnet 4.6/low fixture. All 215 canonical files and all seven cleanup checks pass independent verification. These are profile-19 results and are not relabeled as fresh profile-22 runs. - Current Pi digest: `sha256:e92078bee3c23bec4100aa589013a44613d054cd686826534025d8019e9f39a9`. [The readiness plan](https://github.com/paperclipai/paperclip/blob/codex/pi-production-readiness/doc/plans/2026-10-02-pi-production-readiness.md) preserves campaign and failed-attempt provenance. - Merge only after every PR's current-head CI and fresh review pass. Linux CI covers the full suites, build and browser tests. The local embedded Postgres API-authority suite cannot start on this macOS/Node 26 host, so Linux CI must confirm that suite. ### Fresh profile-22 core qualification — 2026-10-08 All seven accepted core cases pass canonically on Pi profile 22, with `openrouter/anthropic/claude-sonnet-4.6` and native-confirmed low thinking. This model is a fixture; production accepts the caller's explicit Pi provider/model. Runtime/install source: `3241a992f2a7703e59e97ed0fd3e5d6405de4401`. Frozen accepted harness: `1a4408a48cfb5a1f094a311141c257c92cd7a893`. Immutable cloud image: `ghcr.io/paperclipai/paperclip-daytona-runner@sha256:506f22db7edd78f37c0c40bec1cc084af1850455026dbf467194bfbb8fcef141`. Pi digest: `sha256:e92078bee3c23bec4100aa589013a44613d054cd686826534025d8019e9f39a9`. [Hosted Linux image and clean-install verification](https://github.com/paperclipai/paperclip/actions/runs/37868328023) passes, including all 20 source-bound archives, normal CLI/Pi setup, companion import and the production pack reader. This exact installation source includes the latest master integration and the corrected Pi warm instruction-root fence. Full local typecheck/build and current-head hosted CI verify the final stack. All 13 focused real-root regressions pass. The full local executor suite passed 662 tests; 15 database tests could not start the Mac embedded PostgreSQL service. Hosted Linux CI passes the full required verification and E2E checks. These fresh results keep their own source identity; profile-19 results remain historical. | Core path | Canonical campaign | Retained archive SHA-256 | | --- | --- | --- | | File edit, validation, download and Done | `pi-core22-replyfix-0-1791511228` | 23 files; `a473e8603a3dd4737863291f8d3d1e392391f0b16d433c3e0e0e9d8baf7a97b0` | | Pending question and controller restart | `pi-core22-replyfix-1-1791511376` | 33 files; `6b829c4eb74e1f32a89c692a4ae7130dbfc1c6d3cf13915effe2103d9e242c8e` | | Three-turn session/process/workspace continuity | `pi-core22-replyfix-2-1791511587` | 23 files; `7a87021f8f9a3fdd3c58bb4467f8d82c635e3ea4795d6e75f144d9aa14818df8` | | Four typed questions and browser reconnects | `pi-core22-replyfix-3-1791511881` | 42 files; `9e31755252be1f4f9cb0626c984c142d4d1ae5f5bee3a7af08444db8d12c280a` | | Plan approval and completion | `pi-core22-replyfix-4-1791512031` | 22 files; `a0383ce1aab38e7b5a25ce0e9dd3bebea5c037ebd96ae6b29dae19015da2ae2c` | | Same-turn steering and permission denial | `pi-core22-replyfix-5-1791512261` | 39 files; `c929b8c7070f0b66aedc17e65ca46e6beab1e363926ac9f7e2a75fb250f05949` | | Stop during pending permission | `pi-core22-replyfix-6-1791512390` | 33 files; `7f0a58ae0f4d5bfc76149435f4e322537089c5bd16e7ffe9b5ad71f10a621a07` | All 215 canonical files (28714587 bytes) are independently hash-verified. All seven cleanup grades pass, with no owned runtime process or temporary root after each case. Automatic retries are zero. The owned cloud host stopped normally after retention. The prior profile-22 warm attempt remains failed and separately retained: archive SHA-256 `1e54eba5ec72b50cee1534b23d1d1d4f21a090006b8a64501ba70db972abfde5`. Its original canonical classification is preserved. Diagnosis reproduced a product bug comparing an agent-files root against an unset checkpoint-only field. The fix stores the admitted physical root separately from the adopted per-run collection capability. The real-root regression fails before the fix and passes afterward, including rejection of a changed physical root. Fixture, grader, model and all seven accepted case IDs are unchanged; this fresh campaign tests final-reply publication after file registration first. The intermediate restart attempt also remains failed and retained: archive SHA-256 `5dcaefdf1d17cf4cd54fd4cf810f45e736667392339b8ce7caf08bb4e225277f`. Its original canonical classification is preserved. Pi resumed, wrote the verified answer and completed its task; exact runner suspension was proven, but idle stop consumed about 5.2s and left under 3s for the drain acknowledgement. The Pi-only default shutdown grace is now 15s, preserving a full 5s drain round trip and a finite suspension reserve. Explicit caller deadlines, other provider defaults, literal drain receipts and exact suspension identity checks remain unchanged. The timing regression fails before this correction and passes afterward; all 18 focused settlement tests and Runner typecheck pass. The final-source file attempt is also preserved as failed (`candidate_failure`), archive SHA-256 `db6767b6773ea618997927ac77bdb005a5ac81492c7b9c0ffbc900449f829bc9`. Native edit, validation, exact downloadable artifact and Done/succeeded all passed, and the exact final reply was durably recorded. A workspace recovery owner completed before the live heartbeat reached presentation, leaving that reply absent from task chat. Recovery now materializes only a completed final reply from the accepted turn of an ordinary internal Done task, preserving issue/run/contract binding, suppression, external-chat authorization and same-run deduplication. The database regression covers the generated file-preparation receipt, suppression, unapproved external continuation and replay. Server typecheck and all 49 response-selection tests pass; hosted Linux verifies the database regression because embedded PostgreSQL cannot start on this Mac. The delayed-final-answer database regression passes on [the final root-source Linux server shard](https://github.com/paperclipai/paperclip/actions/runs/37868262553/job/113628594152), alongside 1,108 passing tests. The first root Runner shard had one unchanged durable-resume test exceed its 5-second timeout; the identical top-source shard and the isolated exact test passed. One rerun of that failed job and its required aggregate passed without source or test changes. The original failed job log and the single-rerun receipt remain retained. ### October 9 merge verification Current merge head: `5a8fe63512a7166aaef5cf50065a25008aa8b44b`. All current-head checks pass, including `ci / verify` and `ci / e2e`; exact-head Greptile review is 5/5 with no unresolved threads. Current master conflicts are resolved. The user authorized the maintainer override of the code-owner review gate after these checks. The seven retained live core cases remain bound to source `3241a992f2a7703e59e97ed0fd3e5d6405de4401` and its recorded cloud image. ## Risks - The security correction changes the dependency closure and profile identity. Old sessions must reopen on the new profile. Exact identities and credential bindings fail closed. - The runner remains experimental and requires explicit selection. Legacy Pi Local is unchanged. Caller model IDs pass through; the E2E model is a fixture. - Accounting and the broad platform/provider matrix remain deferred. This merge does not publish a release or deploy a service. ## Model Used OpenAI GPT-6 through Codex assisted with reasoning, repository inspection, editing and tool use. The exact serving ID and context window are not exposed in this session. Final live qualification uses Pi 1.0.0 with `openrouter/anthropic/claude-sonnet-4.6` and native-confirmed low thinking. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
381 lines
19 KiB
TypeScript
381 lines
19 KiB
TypeScript
export const PAPERCLIP_QUESTION_SET_SCHEMA = "paperclip.question_set.v1" as const;
|
|
export const PAPERCLIP_QUESTION_RESPONSE_SCHEMA = "paperclip.question_response.v1" as const;
|
|
export const PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2 = "paperclip.runtime_request.v2" as const;
|
|
|
|
export type PaperclipQuestionAnswerMode = "single_select" | "multi_select" | "text";
|
|
|
|
export interface PaperclipQuestionOption {
|
|
id: string;
|
|
label: string;
|
|
description?: string;
|
|
recommended?: boolean;
|
|
}
|
|
|
|
export interface PaperclipQuestionCustomAnswer {
|
|
enabled: true;
|
|
label?: string;
|
|
placeholder?: string;
|
|
}
|
|
|
|
export interface PaperclipQuestionTextValidation {
|
|
minLength?: number;
|
|
maxLength?: number;
|
|
pattern?: string;
|
|
inputType?: "text" | "number" | "integer";
|
|
minimum?: number;
|
|
maximum?: number;
|
|
}
|
|
|
|
export interface PaperclipQuestion {
|
|
id: string;
|
|
header?: string;
|
|
prompt: string;
|
|
helpText?: string;
|
|
required: boolean;
|
|
answerMode: PaperclipQuestionAnswerMode;
|
|
/** Editable starting text, never an implicit or submitted answer. Text mode only. */
|
|
initialText?: string;
|
|
options?: PaperclipQuestionOption[];
|
|
customAnswer?: PaperclipQuestionCustomAnswer;
|
|
textValidation?: PaperclipQuestionTextValidation;
|
|
}
|
|
|
|
export interface PaperclipQuestionSet {
|
|
schema: typeof PAPERCLIP_QUESTION_SET_SCHEMA;
|
|
title?: string;
|
|
description?: string;
|
|
submitLabel?: string;
|
|
questions: PaperclipQuestion[];
|
|
}
|
|
|
|
export interface PaperclipQuestionAnswer {
|
|
selectedOptionIds?: string[];
|
|
text?: string;
|
|
customText?: string;
|
|
}
|
|
|
|
export interface PaperclipQuestionResponse {
|
|
schema: typeof PAPERCLIP_QUESTION_RESPONSE_SCHEMA;
|
|
answers: Record<string, PaperclipQuestionAnswer>;
|
|
}
|
|
|
|
export interface PaperclipRuntimeRequestOrigin {
|
|
adapter: string;
|
|
provider?: string;
|
|
method?: string;
|
|
}
|
|
|
|
export interface PaperclipRuntimeInputRequest {
|
|
schema: typeof PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2;
|
|
requestKind: "runtime";
|
|
requestId: string;
|
|
type: "input";
|
|
status: "pending" | "resolved" | "expired" | "cancelled";
|
|
prompt: string;
|
|
input: PaperclipQuestionSet;
|
|
origin?: PaperclipRuntimeRequestOrigin;
|
|
turnId?: string;
|
|
itemId?: string;
|
|
}
|
|
|
|
export class PaperclipQuestionValidationError extends Error {
|
|
readonly code = "invalid_question_response" as const;
|
|
readonly path: string;
|
|
|
|
constructor(path: string, detail: string) {
|
|
super(`${path}: ${detail}`);
|
|
this.name = "PaperclipQuestionValidationError";
|
|
this.path = path;
|
|
}
|
|
}
|
|
|
|
function record(value: unknown): Record<string, unknown> | null {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
? (value as Record<string, unknown>)
|
|
: null;
|
|
}
|
|
|
|
function rejectUnknownKeys(
|
|
value: Record<string, unknown>,
|
|
allowed: readonly string[],
|
|
path: string,
|
|
): void {
|
|
const allowedKeys = new Set(allowed);
|
|
const unknown = Object.keys(value).find((key) => !allowedKeys.has(key));
|
|
if (unknown !== undefined) {
|
|
throw new PaperclipQuestionValidationError(`${path}/${unknown}`, "is not part of the canonical response contract");
|
|
}
|
|
}
|
|
|
|
function requiredText(value: unknown, path: string, maxLength = 4_000): string {
|
|
if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
|
|
throw new PaperclipQuestionValidationError(path, `must be a non-empty string of at most ${maxLength} characters`);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function optionalText(value: unknown, path: string, maxLength = 4_000): string | undefined {
|
|
if (value === undefined) return undefined;
|
|
if (typeof value !== "string" || value.length > maxLength) {
|
|
throw new PaperclipQuestionValidationError(path, `must be a string of at most ${maxLength} characters`);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function optionalFiniteNumber(value: unknown, path: string): number | undefined {
|
|
if (value === undefined) return undefined;
|
|
if (typeof value !== "number" || !Number.isFinite(value)) {
|
|
throw new PaperclipQuestionValidationError(path, "must be a finite number");
|
|
}
|
|
return value;
|
|
}
|
|
|
|
/** Parse and sanitize the provider-neutral presentation contract at an adapter boundary. */
|
|
export function parsePaperclipQuestionSet(value: unknown): PaperclipQuestionSet {
|
|
const candidate = record(value);
|
|
if (candidate === null || candidate.schema !== PAPERCLIP_QUESTION_SET_SCHEMA) {
|
|
throw new PaperclipQuestionValidationError("/input", `must use ${PAPERCLIP_QUESTION_SET_SCHEMA}`);
|
|
}
|
|
if (!Array.isArray(candidate.questions) || candidate.questions.length === 0 || candidate.questions.length > 64) {
|
|
throw new PaperclipQuestionValidationError("/input/questions", "must contain between 1 and 64 questions");
|
|
}
|
|
const questionIds = new Set<string>();
|
|
const questions = candidate.questions.map((rawQuestion, questionIndex): PaperclipQuestion => {
|
|
const path = `/input/questions/${questionIndex}`;
|
|
const question = record(rawQuestion);
|
|
if (question === null) throw new PaperclipQuestionValidationError(path, "must be an object");
|
|
const id = requiredText(question.id, `${path}/id`, 160);
|
|
if (questionIds.has(id)) throw new PaperclipQuestionValidationError(`${path}/id`, "must be unique");
|
|
questionIds.add(id);
|
|
const answerMode = question.answerMode;
|
|
if (answerMode !== "single_select" && answerMode !== "multi_select" && answerMode !== "text") {
|
|
throw new PaperclipQuestionValidationError(`${path}/answerMode`, "must be single_select, multi_select, or text");
|
|
}
|
|
if (typeof question.required !== "boolean") {
|
|
throw new PaperclipQuestionValidationError(`${path}/required`, "must be boolean");
|
|
}
|
|
if (Array.isArray(question.options) && question.options.length > 128) {
|
|
throw new PaperclipQuestionValidationError(`${path}/options`, "cannot contain more than 128 options");
|
|
}
|
|
const options: PaperclipQuestionOption[] | undefined = Array.isArray(question.options)
|
|
? question.options.map((rawOption, optionIndex) => {
|
|
const optionPath = `${path}/options/${optionIndex}`;
|
|
const option = record(rawOption);
|
|
if (option === null) throw new PaperclipQuestionValidationError(optionPath, "must be an object");
|
|
if (option.recommended !== undefined && typeof option.recommended !== "boolean") {
|
|
throw new PaperclipQuestionValidationError(`${optionPath}/recommended`, "must be boolean");
|
|
}
|
|
return {
|
|
id: requiredText(option.id, `${optionPath}/id`, 160),
|
|
label: requiredText(option.label, `${optionPath}/label`, 1_000),
|
|
...(optionalText(option.description, `${optionPath}/description`) !== undefined
|
|
? { description: optionalText(option.description, `${optionPath}/description`) }
|
|
: {}),
|
|
...(option.recommended !== undefined ? { recommended: option.recommended } : {}),
|
|
};
|
|
})
|
|
: undefined;
|
|
if (options !== undefined && new Set(options.map((option) => option.id)).size !== options.length) {
|
|
throw new PaperclipQuestionValidationError(`${path}/options`, "option IDs must be unique within a question");
|
|
}
|
|
if (answerMode !== "text" && (!options || options.length === 0)) {
|
|
throw new PaperclipQuestionValidationError(`${path}/options`, "select questions require at least one option");
|
|
}
|
|
if (answerMode === "text" && options !== undefined && options.length > 0) {
|
|
throw new PaperclipQuestionValidationError(`${path}/options`, "text questions cannot define options");
|
|
}
|
|
const initialText = question.initialText;
|
|
if (initialText !== undefined && (
|
|
typeof initialText !== "string"
|
|
|| initialText.length > 200_000
|
|
|| Array.from(initialText).length > 100_000
|
|
)) {
|
|
throw new PaperclipQuestionValidationError(`${path}/initialText`, "must be a string of at most 100000 Unicode code points");
|
|
}
|
|
if (initialText !== undefined && answerMode !== "text") {
|
|
throw new PaperclipQuestionValidationError(`${path}/initialText`, "only text questions can define initial text");
|
|
}
|
|
const custom = record(question.customAnswer);
|
|
const customAnswer = custom === null
|
|
? undefined
|
|
: {
|
|
enabled: true as const,
|
|
...(optionalText(custom.label, `${path}/customAnswer/label`, 1_000) !== undefined
|
|
? { label: optionalText(custom.label, `${path}/customAnswer/label`, 1_000) }
|
|
: {}),
|
|
...(optionalText(custom.placeholder, `${path}/customAnswer/placeholder`, 1_000) !== undefined
|
|
? { placeholder: optionalText(custom.placeholder, `${path}/customAnswer/placeholder`, 1_000) }
|
|
: {}),
|
|
};
|
|
if (custom !== null && custom.enabled !== true) {
|
|
throw new PaperclipQuestionValidationError(`${path}/customAnswer/enabled`, "must be true when customAnswer is present");
|
|
}
|
|
if (answerMode === "text" && customAnswer !== undefined) {
|
|
throw new PaperclipQuestionValidationError(`${path}/customAnswer`, "text questions do not use a separate custom answer");
|
|
}
|
|
const validation = record(question.textValidation);
|
|
const textValidation: PaperclipQuestionTextValidation | undefined = validation === null
|
|
? undefined
|
|
: {
|
|
...(typeof validation.minLength === "number" ? { minLength: validation.minLength } : {}),
|
|
...(typeof validation.maxLength === "number" ? { maxLength: validation.maxLength } : {}),
|
|
...(optionalText(validation.pattern, `${path}/textValidation/pattern`, 1_000) !== undefined
|
|
? { pattern: optionalText(validation.pattern, `${path}/textValidation/pattern`, 1_000) }
|
|
: {}),
|
|
...(validation.inputType === "number" || validation.inputType === "integer" || validation.inputType === "text"
|
|
? { inputType: validation.inputType }
|
|
: {}),
|
|
...(optionalFiniteNumber(validation.minimum, `${path}/textValidation/minimum`) !== undefined
|
|
? { minimum: optionalFiniteNumber(validation.minimum, `${path}/textValidation/minimum`) }
|
|
: {}),
|
|
...(optionalFiniteNumber(validation.maximum, `${path}/textValidation/maximum`) !== undefined
|
|
? { maximum: optionalFiniteNumber(validation.maximum, `${path}/textValidation/maximum`) }
|
|
: {}),
|
|
};
|
|
if (validation !== null) {
|
|
for (const key of ["minLength", "maxLength"] as const) {
|
|
const raw = validation[key];
|
|
if (raw !== undefined && (!Number.isSafeInteger(raw) || (raw as number) < 0 || (raw as number) > 100_000)) {
|
|
throw new PaperclipQuestionValidationError(`${path}/textValidation/${key}`, "must be an integer from 0 through 100000");
|
|
}
|
|
}
|
|
if (validation.inputType !== undefined && !["text", "number", "integer"].includes(String(validation.inputType))) {
|
|
throw new PaperclipQuestionValidationError(`${path}/textValidation/inputType`, "must be text, number, or integer");
|
|
}
|
|
if (textValidation?.minLength !== undefined && textValidation.maxLength !== undefined && textValidation.minLength > textValidation.maxLength) {
|
|
throw new PaperclipQuestionValidationError(`${path}/textValidation`, "minLength cannot exceed maxLength");
|
|
}
|
|
if (textValidation?.minimum !== undefined && textValidation.maximum !== undefined && textValidation.minimum > textValidation.maximum) {
|
|
throw new PaperclipQuestionValidationError(`${path}/textValidation`, "minimum cannot exceed maximum");
|
|
}
|
|
if (textValidation?.pattern !== undefined) {
|
|
try { new RegExp(textValidation.pattern); } catch {
|
|
throw new PaperclipQuestionValidationError(`${path}/textValidation/pattern`, "must be a valid regular expression");
|
|
}
|
|
}
|
|
}
|
|
return {
|
|
id,
|
|
...(optionalText(question.header, `${path}/header`, 1_000) !== undefined
|
|
? { header: optionalText(question.header, `${path}/header`, 1_000) }
|
|
: {}),
|
|
prompt: requiredText(question.prompt, `${path}/prompt`),
|
|
...(optionalText(question.helpText, `${path}/helpText`) !== undefined
|
|
? { helpText: optionalText(question.helpText, `${path}/helpText`) }
|
|
: {}),
|
|
required: question.required,
|
|
answerMode,
|
|
...(initialText !== undefined ? { initialText } : {}),
|
|
...(options !== undefined ? { options } : {}),
|
|
...(customAnswer !== undefined ? { customAnswer } : {}),
|
|
...(textValidation !== undefined ? { textValidation } : {}),
|
|
};
|
|
});
|
|
return {
|
|
schema: PAPERCLIP_QUESTION_SET_SCHEMA,
|
|
...(optionalText(candidate.title, "/input/title", 1_000) !== undefined
|
|
? { title: optionalText(candidate.title, "/input/title", 1_000) }
|
|
: {}),
|
|
...(optionalText(candidate.description, "/input/description", 100_000) !== undefined
|
|
? { description: optionalText(candidate.description, "/input/description", 100_000) }
|
|
: {}),
|
|
...(optionalText(candidate.submitLabel, "/input/submitLabel", 200) !== undefined
|
|
? { submitLabel: optionalText(candidate.submitLabel, "/input/submitLabel", 200) }
|
|
: {}),
|
|
questions,
|
|
};
|
|
}
|
|
|
|
function answerHasValue(answer: PaperclipQuestionAnswer): boolean {
|
|
return Boolean(answer.text?.trim() || answer.customText?.trim() || answer.selectedOptionIds?.length);
|
|
}
|
|
|
|
/** Revalidate untrusted UI input against the persisted question set. */
|
|
export function parsePaperclipQuestionResponse(
|
|
questionSetValue: unknown,
|
|
responseValue: unknown,
|
|
): PaperclipQuestionResponse {
|
|
const questionSet = parsePaperclipQuestionSet(questionSetValue);
|
|
const response = record(responseValue);
|
|
if (response === null || response.schema !== PAPERCLIP_QUESTION_RESPONSE_SCHEMA) {
|
|
throw new PaperclipQuestionValidationError("/response", `must use ${PAPERCLIP_QUESTION_RESPONSE_SCHEMA}`);
|
|
}
|
|
rejectUnknownKeys(response, ["schema", "answers"], "/response");
|
|
const rawAnswers = record(response.answers);
|
|
if (rawAnswers === null) throw new PaperclipQuestionValidationError("/response/answers", "must be an object keyed by question ID");
|
|
const questions = new Map(questionSet.questions.map((question) => [question.id, question]));
|
|
for (const questionId of Object.keys(rawAnswers)) {
|
|
if (!questions.has(questionId)) throw new PaperclipQuestionValidationError(`/response/answers/${questionId}`, "does not match a question in the persisted set");
|
|
}
|
|
const answers: Record<string, PaperclipQuestionAnswer> = {};
|
|
for (const question of questionSet.questions) {
|
|
const path = `/response/answers/${question.id}`;
|
|
const raw = rawAnswers[question.id];
|
|
if (raw === undefined) {
|
|
if (question.required) throw new PaperclipQuestionValidationError(path, "is required");
|
|
continue;
|
|
}
|
|
const answer = record(raw);
|
|
if (answer === null) throw new PaperclipQuestionValidationError(path, "must be an object");
|
|
rejectUnknownKeys(answer, ["selectedOptionIds", "text", "customText"], path);
|
|
const selectedOptionIds = answer.selectedOptionIds === undefined
|
|
? undefined
|
|
: Array.isArray(answer.selectedOptionIds) && answer.selectedOptionIds.every((entry) => typeof entry === "string")
|
|
? [...answer.selectedOptionIds]
|
|
: null;
|
|
if (selectedOptionIds === null) throw new PaperclipQuestionValidationError(`${path}/selectedOptionIds`, "must be an array of strings");
|
|
if (selectedOptionIds !== undefined && new Set(selectedOptionIds).size !== selectedOptionIds.length) {
|
|
throw new PaperclipQuestionValidationError(`${path}/selectedOptionIds`, "cannot contain duplicates");
|
|
}
|
|
const textValue = optionalText(answer.text, `${path}/text`, 100_000);
|
|
const customText = optionalText(answer.customText, `${path}/customText`, 100_000);
|
|
if (question.answerMode === "text") {
|
|
if (selectedOptionIds?.length || customText !== undefined) throw new PaperclipQuestionValidationError(path, "text answers only carry text");
|
|
} else {
|
|
if (textValue !== undefined) throw new PaperclipQuestionValidationError(path, "select answers do not carry text");
|
|
const allowed = new Set((question.options ?? []).map((option) => option.id));
|
|
for (const optionId of selectedOptionIds ?? []) {
|
|
if (!allowed.has(optionId)) throw new PaperclipQuestionValidationError(`${path}/selectedOptionIds`, `contains unknown option ${optionId}`);
|
|
}
|
|
if (question.answerMode === "single_select" && (selectedOptionIds?.length ?? 0) > 1) {
|
|
throw new PaperclipQuestionValidationError(`${path}/selectedOptionIds`, "single-select answers choose at most one option");
|
|
}
|
|
if (customText !== undefined && question.customAnswer?.enabled !== true) {
|
|
throw new PaperclipQuestionValidationError(`${path}/customText`, "custom answers are not enabled for this question");
|
|
}
|
|
if (customText?.trim() && (selectedOptionIds?.length ?? 0) > 0 && question.answerMode === "single_select") {
|
|
throw new PaperclipQuestionValidationError(path, "single-select answers cannot select an option and a custom answer");
|
|
}
|
|
}
|
|
const parsed: PaperclipQuestionAnswer = {
|
|
...(selectedOptionIds !== undefined ? { selectedOptionIds } : {}),
|
|
...(textValue !== undefined ? { text: textValue } : {}),
|
|
...(customText !== undefined ? { customText } : {}),
|
|
};
|
|
if (question.required && !answerHasValue(parsed)) throw new PaperclipQuestionValidationError(path, "is required");
|
|
const boundedText = question.answerMode === "text" ? parsed.text : parsed.customText;
|
|
if (boundedText !== undefined) {
|
|
const validation = question.textValidation;
|
|
if (validation?.minLength !== undefined && boundedText.length < validation.minLength) {
|
|
throw new PaperclipQuestionValidationError(path, `must contain at least ${validation.minLength} characters`);
|
|
}
|
|
if (validation?.maxLength !== undefined && boundedText.length > validation.maxLength) {
|
|
throw new PaperclipQuestionValidationError(path, `must contain at most ${validation.maxLength} characters`);
|
|
}
|
|
if (validation?.pattern !== undefined && !new RegExp(validation.pattern).test(boundedText)) {
|
|
throw new PaperclipQuestionValidationError(path, "does not match the required format");
|
|
}
|
|
if (validation?.inputType === "number" || validation?.inputType === "integer") {
|
|
const numeric = Number(boundedText);
|
|
if (!Number.isFinite(numeric) || (validation.inputType === "integer" && !Number.isInteger(numeric))) {
|
|
throw new PaperclipQuestionValidationError(path, `must be a valid ${validation.inputType}`);
|
|
}
|
|
if (validation.minimum !== undefined && numeric < validation.minimum) throw new PaperclipQuestionValidationError(path, `must be at least ${validation.minimum}`);
|
|
if (validation.maximum !== undefined && numeric > validation.maximum) throw new PaperclipQuestionValidationError(path, `must be at most ${validation.maximum}`);
|
|
}
|
|
}
|
|
if (answerHasValue(parsed)) answers[question.id] = parsed;
|
|
}
|
|
return { schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA, answers };
|
|
}
|