@auden.to/protocol 0.1.0-alpha.2

package/dist/schemas.js

@@ -0,0 +1,750 @@
+/**
+ * Runtime validation schemas using Valibot.
+ *
+ * Schemas are the single source of truth — TypeScript types in types.ts are
+ * derived from these via `v.InferOutput<typeof Schema>`.
+ *
+ * Callers can use the exported `parse*` wrappers (throw ValiError on invalid
+ * input) or call `v.safeParse(Schema, data)` directly for non-throwing checks.
+ */
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Core enum schemas
+// ---------------------------------------------------------------------------
+export const VerdictSchema = v.picklist(['aligned', 'unguided', 'misaligned']);
+export const GuidingTierSchema = v.picklist(['pattern_match', 'cached', 'llm', 'batch']);
+export const PlatformKindSchema = v.picklist([
+    'claude_code',
+    'cursor',
+    'copilot',
+    'windsurf',
+    'other',
+]);
+export const GuideFileFormatSchema = v.picklist([
+    'agents-md',
+    'agents-dir',
+    'claude-md',
+    'claude-rules',
+    'cursorrules',
+    'cursor-rules',
+    'skill-md',
+]);
+export const EvalProviderKindSchema = v.picklist([
+    'openrouter',
+    'anthropic',
+    'openai-compatible',
+    'google',
+    'ollama',
+]);
+const NonEmptyStringSchema = v.pipe(v.string(), v.minLength(1));
+export const PartialEvalProviderSettingsSchema = v.object({
+    provider: v.optional(EvalProviderKindSchema),
+    model: v.optional(NonEmptyStringSchema),
+    apiKey: v.optional(NonEmptyStringSchema),
+    baseUrl: v.optional(NonEmptyStringSchema),
+    siteUrl: v.optional(NonEmptyStringSchema),
+    siteName: v.optional(NonEmptyStringSchema),
+});
+export const EvalProviderConfigSchema = v.object({
+    provider: EvalProviderKindSchema,
+    model: NonEmptyStringSchema,
+    apiKey: v.optional(NonEmptyStringSchema),
+    baseUrl: NonEmptyStringSchema,
+    siteUrl: v.optional(NonEmptyStringSchema),
+    siteName: v.optional(NonEmptyStringSchema),
+});
+// ---------------------------------------------------------------------------
+// Auth schemas
+// ---------------------------------------------------------------------------
+export const ValidateTokenRequestSchema = v.object({
+    token: v.string(),
+});
+export const ValidateTokenResponseSchema = v.object({
+    valid: v.boolean(),
+    userId: v.optional(v.string()),
+    expiresAt: v.optional(v.string()),
+});
+export const CliTokenMetadataSchema = v.object({
+    token: v.string(),
+    userId: v.string(),
+    createdAt: v.string(),
+    expiresAt: v.string(),
+});
+// ---------------------------------------------------------------------------
+// Guide snapshot schemas
+// ---------------------------------------------------------------------------
+export const GuideSnapshotSchema = v.object({
+    id: v.string(),
+    title: v.string(),
+    content: v.string(),
+    enabled: v.boolean(),
+    updatedAt: v.string(),
+    // origin is `file:{format}:{path}` for imported guides, null/absent
+    // otherwise. contentHash is the SHA-256 of the canonical bytes; the CLI uses
+    // the pair to round-trip imported files back to disk without re-encoding.
+    origin: v.optional(v.nullable(v.string())),
+    contentHash: v.optional(v.nullable(v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/i)))),
+});
+export const GuideBundleResponseSchema = v.object({
+    guides: v.array(GuideSnapshotSchema),
+    pulledAt: v.string(),
+});
+/** Max serialized size (UTF-8 bytes) of an imported guide file's raw content. */
+export const MAX_RAW_GUIDE_CONTENT_BYTES = 512 * 1024;
+/** Max member files a single skill-md payload may carry. */
+export const MAX_SKILL_MEMBER_FILES = 64;
+const BoundedRawContentSchema = v.pipe(v.string(), v.check((value) => new TextEncoder().encode(value).length <= MAX_RAW_GUIDE_CONTENT_BYTES, `rawContent must be at most ${MAX_RAW_GUIDE_CONTENT_BYTES} bytes`));
+const Sha256HexSchema = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/i));
+// Member paths are relative to the skill directory and will be re-created on
+// disk by the export round-trip, so they are constrained to safe relative
+// paths at the schema boundary: forward slashes only, never absolute (POSIX
+// or Windows drive-letter form), no empty / `.` / `..` segments, no control
+// characters, and never the skill's own SKILL.md (the payload itself).
+// Exported so the member-files read path (server response filtering, CLI
+// defense-in-depth before writing to disk) enforces the identical rule.
+export const SkillMemberPathSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(512), v.check((path) => !path.includes('\\'), 'path must use forward slashes'), v.check((path) => !path.startsWith('/') && !/^[a-zA-Z]:/.test(path), 'path must be relative'), v.check((path) => !/[\u0000-\u001f\u007f]/.test(path), 'path must not contain control characters'), v.check((path) => path
+    .split('/')
+    .every((segment) => segment !== '' && segment !== '.' && segment !== '..'), 'path must not contain empty, "." or ".." segments'), v.check((path) => path.toLowerCase() !== 'skill.md', 'path must not shadow the skill’s own SKILL.md'));
+// A sibling file of a skill's SKILL.md (scripts/, references/, assets/,
+// supporting docs), imported alongside it as a guide_file row.
+export const RawSkillMemberFileSchema = v.object({
+    path: SkillMemberPathSchema,
+    rawContent: BoundedRawContentSchema,
+    lastModified: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    content_hash: Sha256HexSchema,
+});
+/** Max skipped-member paths a skill-md payload may report alongside `members`. */
+export const MAX_SKILL_SKIPPED_MEMBER_PATHS = 256;
+// Paths (relative to the skill directory) that discovery found but could not
+// import this run — binary/non-UTF-8, oversized, unreadable, or beyond the
+// member cap. Deliberately looser than SkillMemberPathSchema: these describe
+// what is on the user's disk and are only ever string-matched against stored
+// member paths server-side (never re-created as files), so an odd on-disk
+// filename must not fail the whole payload.
+const SkippedMemberPathSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(512));
+export const RawGuideFilePayloadSchema = v.pipe(v.object({
+    path: v.string(),
+    format: GuideFileFormatSchema,
+    rawContent: BoundedRawContentSchema,
+    lastModified: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    content_hash: Sha256HexSchema,
+    // Only meaningful on `skill-md` payloads. `[]` asserts the skill has no
+    // member files (stale synced rows are removed server-side); omitting the
+    // field means "no member information" and leaves member rows untouched —
+    // `auden rules watch` re-sends a changed SKILL.md without re-reading the
+    // directory, so it must not be interpreted as an empty skill.
+    members: v.optional(v.pipe(v.array(RawSkillMemberFileSchema), v.maxLength(MAX_SKILL_MEMBER_FILES))),
+    // Only alongside `members`: member paths present on disk but not imported
+    // this run. The server must NOT treat their absence from `members` as
+    // removal — a transiently unreadable or newly-oversized file would
+    // otherwise hard-delete its previously synced row.
+    skippedMemberPaths: v.optional(v.pipe(v.array(SkippedMemberPathSchema), v.maxLength(MAX_SKILL_SKIPPED_MEMBER_PATHS))),
+}), v.check((payload) => payload.members === undefined || payload.format === 'skill-md', 'members are only supported on skill-md payloads'), v.check((payload) => payload.skippedMemberPaths === undefined || payload.members !== undefined, 'skippedMemberPaths requires members'), 
+// Case-insensitive uniqueness: the export round-trip re-creates these files
+// on disk, where the default macOS/Windows filesystems fold case — two
+// members differing only by case would silently overwrite each other.
+v.check((payload) => payload.members === undefined ||
+    new Set(payload.members.map((member) => member.path.toLowerCase())).size ===
+        payload.members.length, 'member paths must be unique (case-insensitive)'));
+// A skill guide's member file as served by GET /api/v1/guides/:id/member-files
+// — the export round-trip's read side. Lean by design: member bodies are NOT
+// part of the guide bundle (the eval hot path pulls that every session), they
+// are fetched lazily per skill guide at export time.
+export const GuideMemberFileSchema = v.object({
+    path: SkillMemberPathSchema,
+    content: BoundedRawContentSchema,
+    contentHash: Sha256HexSchema,
+});
+export const GuideMemberFilesResponseSchema = v.pipe(v.object({
+    memberFiles: v.pipe(v.array(GuideMemberFileSchema), v.maxLength(MAX_SKILL_MEMBER_FILES)),
+}), 
+// Mirrors the import payload's rule: on case-folding filesystems two
+// entries differing only by case resolve to one file, and both planning as
+// NEW would let the second silently clobber the first without the
+// OVERWRITE diff prompt. A response that case-collides is malformed.
+v.check((response) => new Set(response.memberFiles.map((file) => file.path.toLowerCase())).size ===
+    response.memberFiles.length, 'member file paths must be unique (case-insensitive)'));
+/** Max number of rules accepted in a single `POST /api/rules/import` request. */
+export const MAX_RULES_IMPORT_BATCH = 100;
+// Envelope-only schema: caps request shape/size before the per-item
+// parseRawGuideFilePayload loop validates each rule in detail (preserves
+// index-aware error reporting — see apps/dashboard/app/api/rules/import+api.ts).
+export const RulesImportRequestSchema = v.object({
+    rules: v.pipe(v.array(v.unknown()), v.maxLength(MAX_RULES_IMPORT_BATCH)),
+});
+// Deletion signal emitted by `auden rules watch` when a previously imported
+// guide file disappears from disk. The dashboard disables (sets active=false)
+// any row whose origin matches `file:{format}:{path}` — the row is retained so
+// re-creating the file flips it back on, and so historical actions are not
+// orphaned.
+export const RawGuideFileDeletionSchema = v.object({
+    path: v.pipe(v.string(), v.minLength(1)),
+    format: GuideFileFormatSchema,
+});
+/** Max number of deletions accepted in a single `POST /api/rules/deletions` request. */
+export const MAX_RULE_DELETIONS_BATCH = 500;
+// Envelope-only schema, matching RulesImportRequestSchema's shape: caps
+// request shape/size before the per-item parseRawGuideFileDeletion loop in
+// apps/dashboard/app/api/rules/deletions+api.ts validates each entry in
+// detail (preserves its index-aware error reporting).
+export const RuleDeletionsRequestSchema = v.object({
+    deletions: v.pipe(v.array(v.unknown()), v.maxLength(MAX_RULE_DELETIONS_BATCH)),
+});
+export const RuleDeletionsResponseSchema = v.object({
+    disabled: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    skipped: v.pipe(v.number(), v.integer(), v.minValue(0)),
+});
+// ---------------------------------------------------------------------------
+// Context bundle schemas (docs/plans/context-layer-mcp-inbox-plan.md — Phase 0)
+// ---------------------------------------------------------------------------
+export const BundleKindSchema = v.picklist(['user', 'inbox', 'system']);
+// url-safe slug, unique per user. Lowercase alphanumerics + hyphens, must start
+// with an alphanumeric so it reads cleanly in a URL/path.
+const BundleSlugSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(64), v.regex(/^[a-z0-9][a-z0-9-]*$/, 'slug must be lowercase alphanumeric with hyphens'));
+export const BundleSchema = v.object({
+    id: v.string(),
+    slug: BundleSlugSchema,
+    name: v.string(),
+    kind: BundleKindSchema,
+    createdAt: v.string(),
+});
+export const BundleListResponseSchema = v.object({
+    bundles: v.array(BundleSchema),
+});
+export const CreateBundleRequestSchema = v.object({
+    slug: BundleSlugSchema,
+    name: v.pipe(v.string(), v.minLength(1), v.maxLength(200)),
+    // Defaults to 'user' server-side. 'inbox' is reserved/auto-created; callers
+    // should not create it explicitly, but the schema stays permissive and the
+    // endpoint enforces reservation.
+    kind: v.optional(BundleKindSchema),
+});
+export const CreateBundleResponseSchema = v.object({
+    bundle: BundleSchema,
+});
+// ---------------------------------------------------------------------------
+// Context item + inbox schemas (context-layer-mcp-inbox-plan.md — Phase 1a)
+// ---------------------------------------------------------------------------
+// The `type` of an item returned to an agent. A `guide` is a canonical guide
+// row; the rest are guide_files rows (documents, references, assets).
+export const ContextItemTypeSchema = v.picklist([
+    'guide',
+    'document',
+    'reference',
+    'asset',
+]);
+// The contentType a caller may write through the context layer. `guide` items
+// own their own lifecycle, so pushes/captures only create guide_files rows.
+export const PushContentTypeSchema = v.picklist(['document', 'reference', 'asset']);
+// Inbox capture is text or an image today (image upload lands in Phase 2b).
+export const InboxContentTypeSchema = v.picklist(['document', 'asset']);
+/** Max serialized size (UTF-8 bytes) of a pushed or captured item's content. */
+export const MAX_CONTEXT_CONTENT_BYTES = 256 * 1024;
+const ContextContentSchema = v.pipe(v.string(), v.check((value) => new TextEncoder().encode(value).length <= MAX_CONTEXT_CONTENT_BYTES, `content must be at most ${MAX_CONTEXT_CONTENT_BYTES} bytes`));
+const ContextItemNameSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(200));
+// The item shape returned to agents. `content` is nullable because an asset
+// stores an object key elsewhere (Phase 2b), not inline text.
+export const ContextItemSchema = v.object({
+    id: v.string(),
+    type: ContextItemTypeSchema,
+    name: v.string(),
+    contentType: v.string(),
+    content: v.nullable(v.string()),
+    origin: v.optional(v.nullable(v.string())),
+    // Monotonic content version of the underlying doc (guide_files), surfaced so a
+    // caller can echo it back as an expected-version precondition. Absent for
+    // `guide` items, which carry no version. See doc-version-history-plan.md.
+    version: v.optional(v.number()),
+    updatedAt: v.string(),
+});
+export const ContextItemsResponseSchema = v.object({
+    items: v.array(ContextItemSchema),
+});
+/** Max number of context item ids a push may cite as its transform sources. */
+export const MAX_TRANSFORM_SOURCE_IDS = 100;
+/**
+ * The ids of the caller-owned context items a pushed document was produced
+ * from (inbox captures, bundle items — any item the caller owns). Shared
+ * between the REST contract and the MCP tool's client-side arg validation so
+ * the two can't drift.
+ */
+export const SourceItemIdsSchema = v.pipe(v.array(v.pipe(v.string(), v.minLength(1))), v.minLength(1), v.maxLength(MAX_TRANSFORM_SOURCE_IDS));
+// Push a canonical item into a bundle. `itemId` present → update in place (the
+// MCP push maps to PUT); absent → create (maps to POST). The dedicated update
+// schema below is what the PUT route validates.
+//
+// `sourceItemIds` (create only, optional) cites the context items the pushed
+// document was produced from. When the caller's own guidance covers the
+// transform (an active guide whose trigger matches, with eval criteria), the
+// server grades the transform against that guidance and records a
+// `context_transform` action with a verdict (context-layer plan, Phase 3c).
+// Auden ships no criteria of its own — no matching guidance means the
+// transform is recorded as 'unguided'.
+export const PushContextRequestSchema = v.object({
+    name: ContextItemNameSchema,
+    contentType: PushContentTypeSchema,
+    content: ContextContentSchema,
+    itemId: v.optional(v.string()),
+    origin: v.optional(v.nullable(v.string())),
+    sourceItemIds: v.optional(SourceItemIdsSchema),
+});
+// The grade the server recorded for a sourced push. `gradingTier` is 'llm'
+// when the caller's guidance was evaluated against the transform, or
+// 'pattern_match' when verdict is 'unguided' (no active guide covered the
+// transform — the signal to write one). When grading infrastructure couldn't
+// run (no LLM configured, over quota, eval failure) NO grade is recorded and
+// the push response omits `transform` entirely — an ungraded round-trip is
+// not a verdict.
+// `gradingTier` is deliberately an open string, not a picklist: a deployed CLI
+// parses this response strictly, and a picklist would turn a future
+// server-side tier (e.g. 'cached') into a hard client error on a successful
+// push.
+export const TransformGradeSchema = v.object({
+    actionId: v.string(),
+    verdict: VerdictSchema,
+    gradingTier: v.string(),
+    reasoning: v.nullable(v.string()),
+});
+export const PushContextResponseSchema = v.object({
+    item: ContextItemSchema,
+    created: v.boolean(),
+    transform: v.optional(TransformGradeSchema),
+});
+// Update a canonical item in place — the edit propagates to every bundle that
+// references it. Both fields are optional so a partial update parses; the route
+// rejects a body that changes nothing.
+export const UpdateContextItemRequestSchema = v.object({
+    itemId: v.pipe(v.string(), v.minLength(1)),
+    name: v.optional(ContextItemNameSchema),
+    content: v.optional(ContextContentSchema),
+    // Optimistic-concurrency precondition: the version the caller last read (from
+    // `ContextItemSchema.version`). When present and it no longer matches the
+    // current version, the update is rejected with 409 instead of silently
+    // clobbering a concurrent write. Omit it to keep last-write-wins behavior.
+    expectedVersion: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+});
+export const UpdateContextItemResponseSchema = v.object({
+    item: ContextItemSchema,
+    updated: v.boolean(),
+});
+export const InboxCaptureRequestSchema = v.object({
+    contentType: InboxContentTypeSchema,
+    content: ContextContentSchema,
+    name: v.optional(ContextItemNameSchema),
+    source: v.optional(v.string()),
+});
+// An inbox item carries capture provenance on top of the base item shape.
+// `capturedAt` is the underlying row's createdAt, so "last 24h" is a filter on it.
+export const InboxItemSchema = v.object({
+    id: v.string(),
+    type: ContextItemTypeSchema,
+    name: v.string(),
+    contentType: v.string(),
+    content: v.nullable(v.string()),
+    source: v.optional(v.nullable(v.string())),
+    // Monotonic content version of the underlying doc, mirroring
+    // `ContextItemSchema.version` — an inbox item is a guide_file too, so a caller
+    // that edits it via PUT can echo this back as an expected-version precondition.
+    version: v.optional(v.number()),
+    capturedAt: v.string(),
+    updatedAt: v.string(),
+});
+export const InboxCaptureResponseSchema = v.object({
+    item: InboxItemSchema,
+});
+export const InboxListResponseSchema = v.object({
+    items: v.array(InboxItemSchema),
+});
+/** Max number of ids accepted in a single `POST /api/v1/context/inbox/archive` request. */
+export const MAX_INBOX_ARCHIVE_BATCH = 500;
+export const InboxArchiveRequestSchema = v.object({
+    ids: v.pipe(v.array(v.pipe(v.string(), v.minLength(1))), v.minLength(1), v.maxLength(MAX_INBOX_ARCHIVE_BATCH)),
+});
+export const InboxArchiveResponseSchema = v.object({
+    archived: v.pipe(v.number(), v.integer(), v.minValue(0)),
+});
+// ---------------------------------------------------------------------------
+// Doc version history (read API)
+// ---------------------------------------------------------------------------
+// One append-only saved version of a context doc (guide_file). Rows are served
+// lazily over REST and never sync through Zero — syncing them would grow every
+// client's initial-sync payload forever. See doc-version-history-plan.md.
+//
+// `authorType` is intentionally an open string, not a picklist: the server owns
+// the closed set ('user' | 'agent' | 'cli'), but a deployed client parses this
+// response strictly, and a picklist would turn any future author kind into a
+// hard parse error on an otherwise valid history read (same reasoning as
+// `TransformGradeSchema.gradingTier`).
+export const ContextItemVersionSchema = v.object({
+    id: v.string(),
+    // Monotonic per doc; the newest version equals the item's current `version`.
+    version: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    contentHash: v.string(),
+    authorType: v.string(),
+    // Non-secret provenance the write path recorded (e.g. bundle slug, capture
+    // source). Never a bearer secret — these rows outlive tokens and ride export.
+    metadata: v.optional(v.nullable(v.record(v.string(), v.unknown()))),
+    createdAt: v.string(),
+});
+// The full version including the snapshotted body, returned by the per-version
+// content fetch. `content` is nullable to stay blob-tier compatible: a future
+// encrypted/blob version stores a hash pointer, not inline text.
+export const ContextItemVersionDetailSchema = v.object({
+    id: v.string(),
+    version: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    content: v.nullable(v.string()),
+    contentHash: v.string(),
+    authorType: v.string(),
+    metadata: v.optional(v.nullable(v.record(v.string(), v.unknown()))),
+    createdAt: v.string(),
+});
+// Newest-first page of a doc's version summaries. `nextCursor` is the version
+// number to pass back as `?before=` for the following (older) page, or null
+// once the oldest version has been returned.
+export const ContextItemVersionsResponseSchema = v.object({
+    versions: v.array(ContextItemVersionSchema),
+    nextCursor: v.nullable(v.number()),
+});
+export const ContextItemVersionResponseSchema = v.object({
+    version: ContextItemVersionDetailSchema,
+});
+/** Default and max page size for the version-history list endpoint. */
+export const DEFAULT_VERSIONS_LIMIT = 50;
+export const MAX_VERSIONS_LIMIT = 200;
+// ---------------------------------------------------------------------------
+// Normalized guide schemas
+// ---------------------------------------------------------------------------
+export const NormalizedGuideRuleSchema = v.object({
+    text: NonEmptyStringSchema,
+    section: v.nullable(v.string()),
+});
+export const NormalizedGuideSchema = v.object({
+    rules: v.array(NormalizedGuideRuleSchema),
+    summary: v.string(),
+});
+// ---------------------------------------------------------------------------
+// Sync payload schemas
+// ---------------------------------------------------------------------------
+const DashboardSyncTierSchema = v.picklist([
+    'pattern_match',
+    'cached',
+    'llm',
+    'batch',
+    'unguided',
+]);
+const DashboardGuideSuggestionStatusSchema = v.picklist([
+    'pending',
+    'accepted',
+    'dismissed',
+]);
+const DashboardFeedbackCandidateStatusSchema = v.picklist([
+    'inferred',
+    'confirmed',
+    'dismissed',
+]);
+const DashboardFeedbackSignalTypeSchema = v.picklist([
+    'correction',
+    'approval',
+    'implied_preference',
+    'stated_preference',
+    'skill_suggestion',
+]);
+export const ProposalCitationSchema = v.object({
+    sessionId: v.string(),
+    timestamp: v.optional(v.string()),
+    summary: v.string(),
+});
+/** Max serialized size of an action's `metadata` field — bounds storage bloat. */
+export const MAX_ACTION_METADATA_BYTES = 16 * 1024;
+const ActionMetadataSchema = v.pipe(v.record(v.string(), v.unknown()), v.check((value) => new TextEncoder().encode(JSON.stringify(value)).length <= MAX_ACTION_METADATA_BYTES, `metadata must serialize to at most ${MAX_ACTION_METADATA_BYTES} bytes`));
+// Token usage extracted from an agent's own transcript (e.g. Claude Code
+// JSONL), keyed by model. See docs/plans/token-cost-tracking-plan.md — Phase 1
+// stores raw token counts only; cost is derived server-side in Phase 2.
+export const TokenUsageSchema = v.object({
+    model: NonEmptyStringSchema,
+    provider: v.optional(v.string()),
+    inputTokens: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    outputTokens: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    cacheReadTokens: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
+    cacheWriteTokens: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
+});
+export const DashboardRunUsageSchema = v.object({
+    runId: v.optional(v.string()),
+    sessionId: NonEmptyStringSchema,
+    usage: v.array(TokenUsageSchema),
+});
+// Per-skill Tier-1 "load overhead" token usage extracted from an agent's own
+// transcript (docs/plans/token-cost-tracking-plan.md §13.3) — the precise part
+// of skill-cost attribution: the tokens billed to load a Skill/SKILL.md into
+// context, approximated in v1 as the first-load message's usage. Tier 2
+// (heuristic guided-work spans) is not implemented yet.
+export const SkillUsageEntrySchema = v.object({
+    skillName: NonEmptyStringSchema,
+    model: NonEmptyStringSchema,
+    inputTokens: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    cacheWriteTokens: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
+});
+export const DashboardSkillUsageSchema = v.object({
+    runId: v.optional(v.string()),
+    sessionId: NonEmptyStringSchema,
+    usage: v.array(SkillUsageEntrySchema),
+});
+export const DashboardSyncActionSchema = v.object({
+    id: v.optional(v.string()),
+    adapterId: v.optional(v.string()),
+    runId: v.optional(v.string()),
+    sessionId: v.optional(v.string()),
+    actionType: v.string(),
+    summary: v.string(),
+    filePaths: v.optional(v.array(v.string())),
+    verdict: v.optional(VerdictSchema),
+    gradingTier: v.optional(DashboardSyncTierSchema),
+    guideIds: v.optional(v.array(v.string())),
+    violatedGuideId: v.optional(v.nullable(v.string())),
+    evalReasoning: v.optional(v.nullable(v.string())),
+    metadata: v.optional(v.nullable(ActionMetadataSchema)),
+});
+export const DashboardGuideSuggestionSchema = v.object({
+    id: v.optional(v.string()),
+    content: v.string(),
+    reasoning: v.optional(v.string()),
+    triggerType: v.picklist([
+        'uncovered',
+        'ambiguous',
+        'performance_pattern',
+        'conversational_feedback',
+    ]),
+    sourceActionIds: v.optional(v.array(v.union([v.string(), ProposalCitationSchema]))),
+    status: v.optional(DashboardGuideSuggestionStatusSchema),
+});
+export const DashboardFeedbackCandidateSchema = v.object({
+    id: v.optional(v.string()),
+    signal: v.string(),
+    signalType: DashboardFeedbackSignalTypeSchema,
+    confidence: v.optional(v.pipe(v.number(), v.minValue(0), v.maxValue(1))),
+    occurrences: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+    status: v.optional(DashboardFeedbackCandidateStatusSchema),
+});
+/** Max number of actions accepted in a single `POST /api/sync` request. */
+export const MAX_SYNC_ACTIONS_BATCH = 500;
+/** Max number of guideSuggestions/feedbackCandidates/runUsage entries per sync request. */
+export const MAX_SYNC_AUX_BATCH = 100;
+export const DashboardSyncRequestSchema = v.object({
+    actions: v.optional(v.pipe(v.array(DashboardSyncActionSchema), v.maxLength(MAX_SYNC_ACTIONS_BATCH))),
+    guideSuggestions: v.optional(v.pipe(v.array(DashboardGuideSuggestionSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
+    feedbackCandidates: v.optional(v.pipe(v.array(DashboardFeedbackCandidateSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
+    runUsage: v.optional(v.pipe(v.array(DashboardRunUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
+    skillUsage: v.optional(v.pipe(v.array(DashboardSkillUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
+});
+export const ExtractedGuideSuggestionSchema = v.object({
+    id: v.string(),
+    content: v.string(),
+    reasoning: v.string(),
+    triggerType: v.picklist(['conversational_feedback']),
+    confidence: v.pipe(v.number(), v.minValue(0), v.maxValue(1)),
+    occurrences: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    citations: v.array(ProposalCitationSchema),
+    source: PlatformKindSchema,
+});
+export const ExtractedSkillSuggestionSchema = v.object({
+    id: v.string(),
+    signal: v.string(),
+    confidence: v.pipe(v.number(), v.minValue(0), v.maxValue(1)),
+    occurrences: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    citations: v.array(ProposalCitationSchema),
+    source: PlatformKindSchema,
+});
+export const ExtractedFeedbackBatchSchema = v.object({
+    guideSuggestions: v.array(ExtractedGuideSuggestionSchema),
+    skillSuggestions: v.array(ExtractedSkillSuggestionSchema),
+});
+// ---------------------------------------------------------------------------
+// Agent / eval schemas
+// ---------------------------------------------------------------------------
+export const FindingSchema = v.object({
+    level: v.picklist(['info', 'warning', 'error']),
+    message: v.string(),
+    data: v.optional(v.unknown()),
+});
+export const AgentConfigSchema = v.object({
+    id: v.string(),
+    name: v.string(),
+    description: v.string(),
+    capabilities: v.array(v.string()),
+    meta: v.optional(v.record(v.string(), v.unknown())),
+});
+export const EvalRequestSchema = v.object({
+    agent: AgentConfigSchema,
+    context: v.optional(v.record(v.string(), v.unknown())),
+});
+export const EvalResultSchema = v.object({
+    agentId: v.string(),
+    passed: v.boolean(),
+    summary: v.string(),
+    findings: v.array(FindingSchema),
+});
+export const ProjectionRequestSchema = v.object({
+    agents: v.array(AgentConfigSchema),
+    outputDir: v.string(),
+});
+export const ProjectionResultSchema = v.object({
+    agentsMd: v.string(),
+    agentsDir: v.record(v.string(), v.string()),
+});
+// ---------------------------------------------------------------------------
+// Run-based eval schemas
+// ---------------------------------------------------------------------------
+export const RuleOutcomeSchema = v.picklist(['aligned', 'misaligned', 'not_applicable']);
+export const ActionEntrySchema = v.object({
+    timestamp: v.string(),
+    sessionId: v.string(),
+    toolName: v.string(),
+    filePath: v.optional(v.string()),
+    command: v.optional(v.string()),
+});
+export const RuleVerdictSchema = v.object({
+    rule: v.string(),
+    verdict: RuleOutcomeSchema,
+    reasoning: v.string(),
+});
+export const RunEvalResultSchema = v.object({
+    verdicts: v.array(RuleVerdictSchema),
+    summary: v.string(),
+    score: v.pipe(v.number(), v.minValue(0), v.maxValue(1)),
+});
+// ---------------------------------------------------------------------------
+// Parse wrappers (throw ValiError on invalid input)
+// ---------------------------------------------------------------------------
+export function parseAgentConfig(data) {
+    return v.parse(AgentConfigSchema, data);
+}
+export function parseEvalRequest(data) {
+    return v.parse(EvalRequestSchema, data);
+}
+export function parseEvalResult(data) {
+    return v.parse(EvalResultSchema, data);
+}
+export function parseEvalProviderSettings(data) {
+    return v.parse(PartialEvalProviderSettingsSchema, data);
+}
+export function parseEvalProviderConfig(data) {
+    return v.parse(EvalProviderConfigSchema, data);
+}
+export function parseValidateTokenRequest(data) {
+    return v.parse(ValidateTokenRequestSchema, data);
+}
+export function parseValidateTokenResponse(data) {
+    return v.parse(ValidateTokenResponseSchema, data);
+}
+export function parseCliTokenMetadata(data) {
+    return v.parse(CliTokenMetadataSchema, data);
+}
+export function parseGuideSnapshot(data) {
+    return v.parse(GuideSnapshotSchema, data);
+}
+export function parseGuideBundleResponse(data) {
+    return v.parse(GuideBundleResponseSchema, data);
+}
+export function parseRawGuideFilePayload(data) {
+    return v.parse(RawGuideFilePayloadSchema, data);
+}
+export function parseGuideMemberFilesResponse(data) {
+    return v.parse(GuideMemberFilesResponseSchema, data);
+}
+export function parseRawGuideFileDeletion(data) {
+    return v.parse(RawGuideFileDeletionSchema, data);
+}
+export function parseRuleDeletionsRequest(data) {
+    return v.parse(RuleDeletionsRequestSchema, data);
+}
+export function parseRulesImportRequest(data) {
+    return v.parse(RulesImportRequestSchema, data);
+}
+export function parseRuleDeletionsResponse(data) {
+    return v.parse(RuleDeletionsResponseSchema, data);
+}
+export function parseBundle(data) {
+    return v.parse(BundleSchema, data);
+}
+export function parseBundleListResponse(data) {
+    return v.parse(BundleListResponseSchema, data);
+}
+export function parseCreateBundleRequest(data) {
+    return v.parse(CreateBundleRequestSchema, data);
+}
+export function parseCreateBundleResponse(data) {
+    return v.parse(CreateBundleResponseSchema, data);
+}
+export function parseContextItem(data) {
+    return v.parse(ContextItemSchema, data);
+}
+export function parseContextItemsResponse(data) {
+    return v.parse(ContextItemsResponseSchema, data);
+}
+export function parsePushContextRequest(data) {
+    return v.parse(PushContextRequestSchema, data);
+}
+export function parsePushContextResponse(data) {
+    return v.parse(PushContextResponseSchema, data);
+}
+export function parseUpdateContextItemRequest(data) {
+    return v.parse(UpdateContextItemRequestSchema, data);
+}
+export function parseUpdateContextItemResponse(data) {
+    return v.parse(UpdateContextItemResponseSchema, data);
+}
+export function parseInboxCaptureRequest(data) {
+    return v.parse(InboxCaptureRequestSchema, data);
+}
+export function parseInboxCaptureResponse(data) {
+    return v.parse(InboxCaptureResponseSchema, data);
+}
+export function parseInboxListResponse(data) {
+    return v.parse(InboxListResponseSchema, data);
+}
+export function parseContextItemVersionsResponse(data) {
+    return v.parse(ContextItemVersionsResponseSchema, data);
+}
+export function parseContextItemVersionResponse(data) {
+    return v.parse(ContextItemVersionResponseSchema, data);
+}
+export function parseInboxArchiveRequest(data) {
+    return v.parse(InboxArchiveRequestSchema, data);
+}
+export function parseInboxArchiveResponse(data) {
+    return v.parse(InboxArchiveResponseSchema, data);
+}
+export function parseNormalizedGuide(data) {
+    return v.parse(NormalizedGuideSchema, data);
+}
+export function parseDashboardSyncRequest(data) {
+    return v.parse(DashboardSyncRequestSchema, data);
+}
+export function parseProposalCitation(data) {
+    return v.parse(ProposalCitationSchema, data);
+}
+export function parseExtractedGuideSuggestion(data) {
+    return v.parse(ExtractedGuideSuggestionSchema, data);
+}
+export function parseExtractedSkillSuggestion(data) {
+    return v.parse(ExtractedSkillSuggestionSchema, data);
+}
+export function parseExtractedFeedbackBatch(data) {
+    return v.parse(ExtractedFeedbackBatchSchema, data);
+}
+export function parseProjectionRequest(data) {
+    return v.parse(ProjectionRequestSchema, data);
+}
+export function parseProjectionResult(data) {
+    return v.parse(ProjectionResultSchema, data);
+}
+export function parseActionEntry(data) {
+    return v.parse(ActionEntrySchema, data);
+}
+export function parseRuleVerdict(data) {
+    return v.parse(RuleVerdictSchema, data);
+}
+export function parseRunEvalResult(data) {
+    return v.parse(RunEvalResultSchema, data);
+}
+//# sourceMappingURL=schemas.js.map