{"record":{"id":"bea5f22477754237","repo":"can1357/oh-my-pi","slug":"invalid-label","errorCode":null,"errorMessage":"Invalid ${label}","messagePattern":"Invalid (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/utils/src/acp/schema.ts","lineNumber":37,"sourceCode":"export interface ValidationFailure {\n\tsuccess: false;\n\terror: ValidationError;\n}\n/** Runtime validator compatible with the used schema call shape. */\nexport interface Validator<T> {\n\tsafeParse(value: unknown): ValidationSuccess<T> | ValidationFailure;\n\tparse(value: unknown): T;\n}\n\nfunction validator<T>(check: (value: unknown) => boolean, label: string): Validator<T> {\n\treturn {\n\t\tsafeParse(value) {\n\t\t\treturn check(value)\n\t\t\t\t? { success: true, data: value as T }\n\t\t\t\t: { success: false, error: { issues: [{ path: [], message: `Invalid ${label}` }] } };\n\t\t},\n\t\tparse(value) {\n\t\t\tif (!check(value)) throw new Error(`Invalid ${label}`);\n\t\t\treturn value as T;\n\t\t},\n\t};\n}\n\nfunction objectWithString(value: unknown, key: string): boolean {\n\treturn typeof value === \"object\" && value !== null && typeof (value as Record<string, unknown>)[key] === \"string\";\n}\n\nfunction validModes(value: unknown): boolean {\n\tif (value === undefined || value === null) return true;\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst modes = value as Record<string, unknown>;\n\treturn (\n\t\ttypeof modes.currentModeId === \"string\" &&\n\t\tArray.isArray(modes.availableModes) &&\n\t\tmodes.availableModes.every(mode => objectWithString(mode, \"id\") && objectWithString(mode, \"name\"))\n\t);","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/acp/schema.ts#L19-L55","documentation":"The lightweight runtime validator in packages/utils/src/acp/schema.ts wraps a boolean check function with a Zod-compatible surface. Its 'parse' method throws Error(`Invalid ${label}`) when the value fails the structural check for the labeled schema (e.g. a session/prompt response shape). safeParse returns the same message as an issue without throwing.","triggerScenarios":"Calling parse(value) on an ACP protocol response (NewSessionResponse, LoadSessionResponse, PromptResponse, ForkSessionResponse, SessionNotification) that is missing required string fields, is not an object, is an array, or has malformed nested structures (e.g. modes.currentModeId not a string, availableModes entries lacking string id/name).","commonSituations":"An ACP agent or client peer returning a non-conformant response after a version drift between protocol revisions; a custom agent implementation missing required response fields; response JSON parsed from stdout lines that contains an error object instead of the expected success shape.","solutions":["Log/inspect the raw value passed to parse and compare it against the schema's required fields.","Use safeParse instead of parse to get a structured failure (issues array) instead of a throw, and branch on success.","Upgrade or align the peer (agent/client) so both sides speak the same ACP protocol revision.","Handle protocol error responses before handing payloads to the schema validator."],"exampleFix":"// before\nconst response = schema.parse(raw);\n// after\nconst result = schema.safeParse(raw);\nif (!result.success) throw new Error(`Bad agent response: ${result.error.issues[0]?.message}`);\nconst response = result.data;","handlingStrategy":"validation","validationCode":"const result = schema.safeParse(raw);\nif (!result.success) {\n  console.error(\"ACP response rejected:\", result.error.issues);\n  return null;\n}\nconst response = result.data;","typeGuard":"function isObjectWithString(v: unknown, key: string): v is Record<string, string> {\n  return typeof v === \"object\" && v !== null && !Array.isArray(v) && typeof (v as Record<string, unknown>)[key] === \"string\";\n}","tryCatchPattern":"try {\n  return schema.parse(raw);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"Invalid \")) {\n    throw new Error(`ACP schema violation: ${err.message}; payload=${JSON.stringify(raw).slice(0, 200)}`);\n  }\n  throw err;\n}","preventionTips":["Prefer safeParse so failures are structured data rather than throws.","Pin/align ACP protocol versions between client and agent peers.","Log the offending raw payload whenever validation fails to spot field drift quickly."],"tags":["acp","schema-validation","protocol"],"backgroundTag":"schema-validation-failed","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}