@kya-os/cli 2.0.0 → 2.0.3

package/node_modules/@kya-os/contracts/dist/agentshield-api/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * AgentShield/Bouncer API Type Definitions
+ *
+ * TypeScript interfaces matching the AgentShield dashboard API contract.
+ * These types ensure parity between xmcp-i clients and the AgentShield service.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentShieldAPIError = void 0;
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * AgentShield API error class
+ */
+class AgentShieldAPIError extends Error {
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "AgentShieldAPIError";
+    }
+}
+exports.AgentShieldAPIError = AgentShieldAPIError;

package/node_modules/@kya-os/contracts/dist/attribution/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Attribution Evidence
+ *
+ * Proof that a SPECIFIC AI agent DID authored a SPECIFIC git commit -- the
+ * wire shape POSTed by `dco verify --emit` (review-loop P27) to
+ * know-that-ai's `POST /api/v1/attribution/evidence` (review-loop P26),
+ * which independently re-verifies the claim rather than trusting it.
+ *
+ * Mirrors `dco verify`'s own three-verdict authorship check (review-loop
+ * P25, packages/cli/src/utils/dco/authorship.ts's `CommitAuthorshipVerification`)
+ * field for field -- the emitter forwards its own verdict JSON almost
+ * verbatim, which is why this schema's field names are camelCase like the
+ * CLI's output rather than this package's usual snake_case wire convention
+ * elsewhere.
+ *
+ * Deliberately its own top-level subpath (`@kya-os/contracts/attribution`),
+ * not folded into `./proof`: the P20 exports-integrity guard
+ * (scripts/check-exports-integrity.mjs) treats `proof` as a deprecated
+ * flat/dir shim slated for removal in contracts 2.0.0, and this schema is
+ * unrelated to the proof subsystem's response-signing proofs anyway.
+ */
+import { z } from "zod";
+/**
+ * `authored` — the commit is cryptographically signed by the agent's own
+ *   key (confirmed by both `dco verify`'s local check and, once submitted,
+ *   the receiving endpoint's own independent re-verification).
+ * `registered-only` — the agent DID is registered, but the commit's
+ *   signature does not check out against it.
+ * `unverified` — neither fact could be established.
+ *
+ * The full three-value enum is accepted here (not narrowed to
+ * `z.literal("authored")`) so a receiving endpoint can run its own
+ * `verdict !== "authored"` check and report an explanatory rejection,
+ * rather than a submission failing as a generic schema/enum error before
+ * that explanation ever runs. `dco verify --emit` itself still only ever
+ * calls the endpoint at all when its own verdict is already `authored` —
+ * see that command's doc comment.
+ */
+export declare const AttributionVerdictSchema: z.ZodEnum<["authored", "registered-only", "unverified"]>;
+export type AttributionVerdict = z.infer<typeof AttributionVerdictSchema>;
+/**
+ * Wire shape POSTed to know-that-ai's `POST /api/v1/attribution/evidence`.
+ * The `agentDid`/`repo` length caps mirror that endpoint's
+ * `attribution_evidence` table columns (both `varchar(255)`): without them
+ * an oversized value passes client-side validation and reaches the
+ * receiving endpoint's insert, where it fails as an uncaught 500 instead of
+ * a controlled 400.
+ */
+export declare const AttributionEvidenceSchema: z.ZodObject<{
+    /** The agent DID the emitter claims authored the commit. */
+    agentDid: z.ZodString;
+    /** GitHub repo as "owner/repo" (no scheme, no whitespace). */
+    repo: z.ZodString;
+    /** Full 40-character git commit SHA (case-insensitive hex). */
+    commitSha: z.ZodString;
+    verdict: z.ZodEnum<["authored", "registered-only", "unverified"]>;
+    /** OpenSSH `SHA256:<base64-no-padding>` fingerprint of the signing key. */
+    keyFingerprint: z.ZodString;
+    /** The emitter's own GitHub-signature verification outcome string. */
+    githubVerificationReason: z.ZodString;
+    /** ISO-8601 timestamp of when the emitter performed its verification. */
+    verifiedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    agentDid: string;
+    verifiedAt: string;
+    verdict: "unverified" | "authored" | "registered-only";
+    repo: string;
+    commitSha: string;
+    keyFingerprint: string;
+    githubVerificationReason: string;
+}, {
+    agentDid: string;
+    verifiedAt: string;
+    verdict: "unverified" | "authored" | "registered-only";
+    repo: string;
+    commitSha: string;
+    keyFingerprint: string;
+    githubVerificationReason: string;
+}>;
+export type AttributionEvidence = z.infer<typeof AttributionEvidenceSchema>;

package/node_modules/@kya-os/contracts/dist/attribution/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Attribution Evidence
+ *
+ * Proof that a SPECIFIC AI agent DID authored a SPECIFIC git commit -- the
+ * wire shape POSTed by `dco verify --emit` (review-loop P27) to
+ * know-that-ai's `POST /api/v1/attribution/evidence` (review-loop P26),
+ * which independently re-verifies the claim rather than trusting it.
+ *
+ * Mirrors `dco verify`'s own three-verdict authorship check (review-loop
+ * P25, packages/cli/src/utils/dco/authorship.ts's `CommitAuthorshipVerification`)
+ * field for field -- the emitter forwards its own verdict JSON almost
+ * verbatim, which is why this schema's field names are camelCase like the
+ * CLI's output rather than this package's usual snake_case wire convention
+ * elsewhere.
+ *
+ * Deliberately its own top-level subpath (`@kya-os/contracts/attribution`),
+ * not folded into `./proof`: the P20 exports-integrity guard
+ * (scripts/check-exports-integrity.mjs) treats `proof` as a deprecated
+ * flat/dir shim slated for removal in contracts 2.0.0, and this schema is
+ * unrelated to the proof subsystem's response-signing proofs anyway.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttributionEvidenceSchema = exports.AttributionVerdictSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * `authored` — the commit is cryptographically signed by the agent's own
+ *   key (confirmed by both `dco verify`'s local check and, once submitted,
+ *   the receiving endpoint's own independent re-verification).
+ * `registered-only` — the agent DID is registered, but the commit's
+ *   signature does not check out against it.
+ * `unverified` — neither fact could be established.
+ *
+ * The full three-value enum is accepted here (not narrowed to
+ * `z.literal("authored")`) so a receiving endpoint can run its own
+ * `verdict !== "authored"` check and report an explanatory rejection,
+ * rather than a submission failing as a generic schema/enum error before
+ * that explanation ever runs. `dco verify --emit` itself still only ever
+ * calls the endpoint at all when its own verdict is already `authored` —
+ * see that command's doc comment.
+ */
+exports.AttributionVerdictSchema = zod_1.z.enum([
+    "authored",
+    "registered-only",
+    "unverified",
+]);
+/**
+ * Wire shape POSTed to know-that-ai's `POST /api/v1/attribution/evidence`.
+ * The `agentDid`/`repo` length caps mirror that endpoint's
+ * `attribution_evidence` table columns (both `varchar(255)`): without them
+ * an oversized value passes client-side validation and reaches the
+ * receiving endpoint's insert, where it fails as an uncaught 500 instead of
+ * a controlled 400.
+ */
+exports.AttributionEvidenceSchema = zod_1.z.object({
+    /** The agent DID the emitter claims authored the commit. */
+    agentDid: zod_1.z.string().min(1).max(255),
+    /** GitHub repo as "owner/repo" (no scheme, no whitespace). */
+    repo: zod_1.z
+        .string()
+        .max(255)
+        .regex(/^[^\s/]+\/[^\s/]+$/, 'must be "owner/repo"'),
+    /** Full 40-character git commit SHA (case-insensitive hex). */
+    commitSha: zod_1.z
+        .string()
+        .regex(/^[0-9a-f]{40}$/i, "must be a 40-character hex commit SHA"),
+    verdict: exports.AttributionVerdictSchema,
+    /** OpenSSH `SHA256:<base64-no-padding>` fingerprint of the signing key. */
+    keyFingerprint: zod_1.z.string().min(1),
+    /** The emitter's own GitHub-signature verification outcome string. */
+    githubVerificationReason: zod_1.z.string().min(1),
+    /** ISO-8601 timestamp of when the emitter performed its verification. */
+    verifiedAt: zod_1.z.string().datetime(),
+});

package/node_modules/@kya-os/contracts/dist/audit/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Legacy diagnostic-audit contracts.
+ *
+ * @deprecated New integrations must use the canonical protocol from
+ * `@kya-os/mcp/audit`. This compatibility module intentionally contains no
+ * recorder or assurance logic; it preserves the published type/schema import
+ * path until the next major release.
+ */
+import { z } from "zod";
+import type { AgentIdentity } from "../config/identity.js";
+import type { SessionContext } from "../handshake/index.js";
+/** @deprecated Use canonical `@kya-os/mcp/audit` event inputs. */
+export declare const AuditContextSchema: z.ZodObject<{
+    identity: z.ZodObject<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    session: z.ZodObject<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    requestHash: z.ZodString;
+    responseHash: z.ZodString;
+    verified: z.ZodEnum<["yes", "no"]>;
+    scopeId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requestHash: string;
+    responseHash: string;
+    session: {
+        audience: string;
+        sessionId: string;
+    } & {
+        [k: string]: unknown;
+    };
+    verified: "yes" | "no";
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    scopeId?: string | undefined;
+}, {
+    requestHash: string;
+    responseHash: string;
+    session: {
+        audience: string;
+        sessionId: string;
+    } & {
+        [k: string]: unknown;
+    };
+    verified: "yes" | "no";
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    scopeId?: string | undefined;
+}>;
+/** @deprecated Use canonical `@kya-os/mcp/audit` event inputs. */
+export type AuditContext = {
+    identity: AgentIdentity;
+    session: SessionContext;
+    requestHash: string;
+    responseHash: string;
+    verified: "yes" | "no";
+    scopeId?: string;
+};
+/** @deprecated Use canonical `@kya-os/mcp/audit` event inputs. */
+export declare const AuditEventContextSchema: z.ZodObject<{
+    eventType: z.ZodString;
+    identity: z.ZodObject<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    session: z.ZodObject<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    eventData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    session: {
+        audience: string;
+        sessionId: string;
+    } & {
+        [k: string]: unknown;
+    };
+    eventType: string;
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    eventData?: Record<string, unknown> | undefined;
+}, {
+    session: {
+        audience: string;
+        sessionId: string;
+    } & {
+        [k: string]: unknown;
+    };
+    eventType: string;
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    eventData?: Record<string, unknown> | undefined;
+}>;
+/** @deprecated Use canonical `@kya-os/mcp/audit` event inputs. */
+export type AuditEventContext = {
+    eventType: string;
+    identity: AgentIdentity;
+    session: SessionContext;
+    eventData?: Record<string, any>;
+};
+/** @deprecated Use canonical `@kya-os/mcp/audit` receipt and event types. */
+export type { AuditRecord } from "../proof/index.js";
+/** @deprecated Use canonical `@kya-os/mcp/audit` schemas. */
+export { AuditRecordSchema } from "../proof/index.js";

package/node_modules/@kya-os/contracts/dist/audit/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Legacy diagnostic-audit contracts.
+ *
+ * @deprecated New integrations must use the canonical protocol from
+ * `@kya-os/mcp/audit`. This compatibility module intentionally contains no
+ * recorder or assurance logic; it preserves the published type/schema import
+ * path until the next major release.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditRecordSchema = exports.AuditEventContextSchema = exports.AuditContextSchema = void 0;
+const zod_1 = require("zod");
+/** @deprecated Use canonical `@kya-os/mcp/audit` event inputs. */
+exports.AuditContextSchema = zod_1.z.object({
+    identity: zod_1.z
+        .object({
+        did: zod_1.z.string().min(1),
+        kid: zod_1.z.string().min(1),
+    })
+        .passthrough(),
+    session: zod_1.z
+        .object({
+        sessionId: zod_1.z.string().min(1),
+        audience: zod_1.z.string().min(1),
+    })
+        .passthrough(),
+    requestHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    responseHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    verified: zod_1.z.enum(["yes", "no"]),
+    scopeId: zod_1.z.string().optional(),
+});
+/** @deprecated Use canonical `@kya-os/mcp/audit` event inputs. */
+exports.AuditEventContextSchema = zod_1.z.object({
+    eventType: zod_1.z.string().min(1),
+    identity: zod_1.z
+        .object({
+        did: zod_1.z.string().min(1),
+        kid: zod_1.z.string().min(1),
+    })
+        .passthrough(),
+    session: zod_1.z
+        .object({
+        sessionId: zod_1.z.string().min(1),
+        audience: zod_1.z.string().min(1),
+    })
+        .passthrough(),
+    eventData: zod_1.z.record(zod_1.z.unknown()).optional(),
+});
+/** @deprecated Use canonical `@kya-os/mcp/audit` schemas. */
+var index_js_1 = require("../proof/index.js");
+Object.defineProperty(exports, "AuditRecordSchema", { enumerable: true, get: function () { return index_js_1.AuditRecordSchema; } });

package/node_modules/@kya-os/contracts/dist/cli-read/analyze.d.ts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+/**
+ * `GET /api/v1/cli/analyze` -- the CLI's "Analyze" tab.
+ *
+ * A thin re-exposure of `useDashboardStats`'s trend data
+ * (`DashboardStatItem` + its `weeklyTrend: {day,value}[]`) plus
+ * `AgentActivityData.topOutcomes` (checkpoint
+ * `packages/checkpoint-shared/src/types/top-agents.ts`), the same outcome
+ * breakdown (allowed/blocked/challenged/redirected/instructed/unknown) the
+ * dashboard's activity lens already computes.
+ *
+ * @module contracts/cli-read/analyze
+ */
+export declare const CliAnalyzeTrendPointSchema: z.ZodObject<{
+    /** `YYYY-MM-DD`, matching `DashboardStatItem.weeklyTrend[].day`. */
+    day: z.ZodString;
+    value: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    value: number;
+    day: string;
+}, {
+    value: number;
+    day: string;
+}>;
+export type CliAnalyzeTrendPoint = z.infer<typeof CliAnalyzeTrendPointSchema>;
+export declare const CliAnalyzeOutcomesSchema: z.ZodObject<{
+    allowed: z.ZodNumber;
+    blocked: z.ZodNumber;
+    challenged: z.ZodNumber;
+    redirected: z.ZodNumber;
+    instructed: z.ZodNumber;
+    unknown: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    unknown: number;
+    allowed: number;
+    blocked: number;
+    challenged: number;
+    redirected: number;
+    instructed: number;
+}, {
+    unknown: number;
+    allowed: number;
+    blocked: number;
+    challenged: number;
+    redirected: number;
+    instructed: number;
+}>;
+export type CliAnalyzeOutcomes = z.infer<typeof CliAnalyzeOutcomesSchema>;
+export declare const CliAnalyzeSummarySchema: z.ZodObject<{
+    generatedAt: z.ZodString;
+    timeWindow: z.ZodEnum<["hourly", "daily", "weekly", "monthly"]>;
+    totalSessions: z.ZodObject<{
+        current: z.ZodNumber;
+        previous: z.ZodOptional<z.ZodNumber>;
+        percentageChange: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    }, {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    }>;
+    agentSessions: z.ZodObject<{
+        current: z.ZodNumber;
+        previous: z.ZodOptional<z.ZodNumber>;
+        percentageChange: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    }, {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    }>;
+    weeklyTrend: z.ZodArray<z.ZodObject<{
+        /** `YYYY-MM-DD`, matching `DashboardStatItem.weeklyTrend[].day`. */
+        day: z.ZodString;
+        value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        day: string;
+    }, {
+        value: number;
+        day: string;
+    }>, "many">;
+    outcomes: z.ZodObject<{
+        allowed: z.ZodNumber;
+        blocked: z.ZodNumber;
+        challenged: z.ZodNumber;
+        redirected: z.ZodNumber;
+        instructed: z.ZodNumber;
+        unknown: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        unknown: number;
+        allowed: number;
+        blocked: number;
+        challenged: number;
+        redirected: number;
+        instructed: number;
+    }, {
+        unknown: number;
+        allowed: number;
+        blocked: number;
+        challenged: number;
+        redirected: number;
+        instructed: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    outcomes: {
+        unknown: number;
+        allowed: number;
+        blocked: number;
+        challenged: number;
+        redirected: number;
+        instructed: number;
+    };
+    generatedAt: string;
+    timeWindow: "hourly" | "daily" | "weekly" | "monthly";
+    totalSessions: {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    };
+    agentSessions: {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    };
+    weeklyTrend: {
+        value: number;
+        day: string;
+    }[];
+}, {
+    outcomes: {
+        unknown: number;
+        allowed: number;
+        blocked: number;
+        challenged: number;
+        redirected: number;
+        instructed: number;
+    };
+    generatedAt: string;
+    timeWindow: "hourly" | "daily" | "weekly" | "monthly";
+    totalSessions: {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    };
+    agentSessions: {
+        current: number;
+        previous?: number | undefined;
+        percentageChange?: number | undefined;
+    };
+    weeklyTrend: {
+        value: number;
+        day: string;
+    }[];
+}>;
+export type CliAnalyzeSummary = z.infer<typeof CliAnalyzeSummarySchema>;

package/node_modules/@kya-os/contracts/dist/cli-read/analyze.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliAnalyzeSummarySchema = exports.CliAnalyzeOutcomesSchema = exports.CliAnalyzeTrendPointSchema = void 0;
+const zod_1 = require("zod");
+const common_js_1 = require("./common.js");
+/**
+ * `GET /api/v1/cli/analyze` -- the CLI's "Analyze" tab.
+ *
+ * A thin re-exposure of `useDashboardStats`'s trend data
+ * (`DashboardStatItem` + its `weeklyTrend: {day,value}[]`) plus
+ * `AgentActivityData.topOutcomes` (checkpoint
+ * `packages/checkpoint-shared/src/types/top-agents.ts`), the same outcome
+ * breakdown (allowed/blocked/challenged/redirected/instructed/unknown) the
+ * dashboard's activity lens already computes.
+ *
+ * @module contracts/cli-read/analyze
+ */
+exports.CliAnalyzeTrendPointSchema = zod_1.z.object({
+    /** `YYYY-MM-DD`, matching `DashboardStatItem.weeklyTrend[].day`. */
+    day: zod_1.z.string().min(1),
+    value: zod_1.z.number().nonnegative(),
+});
+exports.CliAnalyzeOutcomesSchema = zod_1.z.object({
+    allowed: zod_1.z.number().int().nonnegative(),
+    blocked: zod_1.z.number().int().nonnegative(),
+    challenged: zod_1.z.number().int().nonnegative(),
+    redirected: zod_1.z.number().int().nonnegative(),
+    instructed: zod_1.z.number().int().nonnegative(),
+    unknown: zod_1.z.number().int().nonnegative(),
+});
+exports.CliAnalyzeSummarySchema = zod_1.z.object({
+    generatedAt: common_js_1.IsoTimestampSchema,
+    timeWindow: zod_1.z.enum(["hourly", "daily", "weekly", "monthly"]),
+    totalSessions: common_js_1.CliStatItemSchema,
+    agentSessions: common_js_1.CliStatItemSchema,
+    weeklyTrend: zod_1.z.array(exports.CliAnalyzeTrendPointSchema).max(common_js_1.CLI_READ_MAX_ROWS),
+    outcomes: exports.CliAnalyzeOutcomesSchema,
+});

package/node_modules/@kya-os/contracts/dist/cli-read/common.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/**
+ * Shared primitives for the checkpoint "CLI read plane" (review-loop P24):
+ * a thin, READ-ONLY re-exposure of the same data the V2 dashboard already
+ * fetches through its own React Query hooks, behind `/api/v1/cli/*` on
+ * checkpoint. Each domain file in this directory (monitor/analyze/projects/
+ * settings) defines the `data` shape for exactly one of those routes.
+ *
+ * Deliberately does NOT define the transport envelope
+ * (`{success,data,metadata}` / `{success,error,metadata}` per checkpoint's
+ * `v1-middleware.ts`) -- that is a wire-framing concern each side parses for
+ * itself (mirroring `cli.ts`'s existing `/api/cli/*` schemas, which are
+ * data-only for the same reason), not a data shape either side validates.
+ *
+ * @module contracts/cli-read/common
+ */
+/** ISO-8601 timestamp, as every checkpoint service layer already emits (`Date`/`z.string().datetime()` fields serialize this way over JSON). */
+export declare const IsoTimestampSchema: z.ZodString;
+/**
+ * The row cap every list in this area's summaries carries (`.max()` on the
+ * array schema, not just a client-side slice): contracts is the source of
+ * truth for what checkpoint's `/api/v1/cli/*` handlers are allowed to
+ * promise, so the bound belongs here, not only in the terminal renderer
+ * that happens to be the first consumer. A summary genuinely needing more
+ * rows than this is itself a sign it should be paginated, not a reason to
+ * raise the cap -- a terminal table has no scroll, and an unbounded list
+ * here is unbounded Ink rendering on every poll tick.
+ */
+export declare const CLI_READ_MAX_ROWS = 100;
+/**
+ * A stat with a trailing comparison, mirroring `DashboardStatItem`
+ * (checkpoint's `packages/checkpoint-shared/src/api/internal.ts`) --
+ * `current`/`previous`/`percentageChange`, the exact shape
+ * `useDashboardStats` already returns for totals the dashboard's own
+ * Monitor and Analyze pages render.
+ */
+export declare const CliStatItemSchema: z.ZodObject<{
+    current: z.ZodNumber;
+    previous: z.ZodOptional<z.ZodNumber>;
+    percentageChange: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    current: number;
+    previous?: number | undefined;
+    percentageChange?: number | undefined;
+}, {
+    current: number;
+    previous?: number | undefined;
+    percentageChange?: number | undefined;
+}>;
+export type CliStatItem = z.infer<typeof CliStatItemSchema>;
+/**
+ * A usage figure against a plan limit, mirroring `UserUsage`/`PlanLimits`
+ * entries from checkpoint's `SettingsData` (`used`/`limit`/`percentage`).
+ * `limit: null` means unlimited on the caller's plan -- `percentage` is
+ * omitted rather than `Infinity`/`NaN` in that case.
+ */
+export declare const CliUsageMetricSchema: z.ZodObject<{
+    used: z.ZodNumber;
+    limit: z.ZodNullable<z.ZodNumber>;
+    percentage: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    used: number;
+    limit: number | null;
+    percentage?: number | undefined;
+}, {
+    used: number;
+    limit: number | null;
+    percentage?: number | undefined;
+}>;
+export type CliUsageMetric = z.infer<typeof CliUsageMetricSchema>;