hivenet 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -0,0 +1,700 @@
+import { z } from 'zod';
+
+/** Triage lifecycle of a single feedback event (owner plane). */
+declare const EVENT_STATUSES: readonly ["new", "seen", "in_progress", "resolved", "wont_fix", "spam"];
+type EventStatus = (typeof EVENT_STATUSES)[number];
+/** Triage lifecycle of a clustered issue (owner plane). */
+declare const ISSUE_STATUSES: readonly ["open", "in_progress", "resolved", "wont_fix", "spam"];
+type IssueStatus = (typeof ISSUE_STATUSES)[number];
+declare const sentimentSchema$1: z.ZodEnum<{
+    positive: "positive";
+    negative: "negative";
+    neutral: "neutral";
+}>;
+type Sentiment$1 = z.infer<typeof sentimentSchema$1>;
+/** Who authored the feedback text (cf. Arize Phoenix `annotator_kind`). */
+declare const authorSchema$1: z.ZodEnum<{
+    agent: "agent";
+    human: "human";
+    hybrid: "hybrid";
+}>;
+type FeedbackAuthor$1 = z.infer<typeof authorSchema$1>;
+/**
+ * Structured failed-task report. `category: "eval"` events carry one of these so the
+ * feedback stream doubles as a replayable eval-candidate corpus.
+ */
+declare const evalReportSchema$1: z.ZodObject<{
+    task: z.ZodString;
+    expected: z.ZodOptional<z.ZodString>;
+    actual: z.ZodOptional<z.ZodString>;
+    mistake: z.ZodOptional<z.ZodString>;
+    attempts: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type EvalReport$1 = z.infer<typeof evalReportSchema$1>;
+/**
+ * Auto-detected context. Every block is optional and best-effort: a missing block means
+ * "not detected or telemetry declined", never an error.
+ */
+declare const feedbackContextSchema$1: z.ZodObject<{
+    agent: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    ci: z.ZodOptional<z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        isPr: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    runtime: z.ZodOptional<z.ZodObject<{
+        platform: z.ZodString;
+        arch: z.ZodString;
+        node: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    project: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    session: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    user: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        authType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type FeedbackContext$1 = z.infer<typeof feedbackContextSchema$1>;
+/**
+ * Vendor-defined enrichment (sdk_version, plan tier, build number). Flat by
+ * design — values stay renderable as chips and queryable via json_extract.
+ * Distinct from `context`, which is what the client auto-detects.
+ */
+declare const metadataSchema$1: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+type FeedbackMetadata$1 = z.infer<typeof metadataSchema$1>;
+declare const feedbackEventSchema$1: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    to: z.ZodOptional<z.ZodString>;
+    feedback: z.ZodString;
+    category: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+        tool: "tool";
+        skill: "skill";
+        prompt: "prompt";
+        docs: "docs";
+        mcp: "mcp";
+        cli: "cli";
+        api: "api";
+        model: "model";
+        eval: "eval";
+        ux: "ux";
+        other: "other";
+    }>, z.ZodString]>>;
+    subject: z.ZodOptional<z.ZodString>;
+    sentiment: z.ZodOptional<z.ZodEnum<{
+        positive: "positive";
+        negative: "negative";
+        neutral: "neutral";
+    }>>;
+    author: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
+        human: "human";
+        hybrid: "hybrid";
+    }>>;
+    thread: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    eval: z.ZodOptional<z.ZodObject<{
+        task: z.ZodString;
+        expected: z.ZodOptional<z.ZodString>;
+        actual: z.ZodOptional<z.ZodString>;
+        mistake: z.ZodOptional<z.ZodString>;
+        attempts: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodObject<{
+        agent: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        ci: z.ZodOptional<z.ZodObject<{
+            name: z.ZodNullable<z.ZodString>;
+            isPr: z.ZodNullable<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        runtime: z.ZodOptional<z.ZodObject<{
+            platform: z.ZodString;
+            arch: z.ZodString;
+            node: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        project: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        session: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        user: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            authType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    client: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>;
+    consent: z.ZodObject<{
+        telemetry: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type FeedbackEvent$1 = z.infer<typeof feedbackEventSchema$1>;
+/** 202 body returned by every conforming ingest endpoint. */
+declare const ingestResponseSchema$1: z.ZodObject<{
+    id: z.ZodString;
+    thread: z.ZodString;
+    resume: z.ZodOptional<z.ZodString>;
+    guidance: z.ZodOptional<z.ZodString>;
+    duplicate: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type IngestResponse$1 = z.infer<typeof ingestResponseSchema$1>;
+/**
+ * Tenant descriptor. Served identically by the hosted registry
+ * (`{registry}/v1/registry/{slug}`) and by self-published well-known files
+ * (`https://{domain}/.well-known/agent-feedback.json`).
+ */
+declare const descriptorSchema$1: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    name: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodURL;
+    writeKey: z.ZodOptional<z.ZodString>;
+    categories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        subject: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    jwks: z.ZodOptional<z.ZodURL>;
+    docs: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+type Descriptor$1 = z.infer<typeof descriptorSchema$1>;
+/**
+ * A codebase a project's feedback is about. Owner-plane wire contract: rides on
+ * every list/get response so a triage agent knows where to go fix things.
+ */
+declare const repoEntrySchema$1: z.ZodObject<{
+    url: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RepoEntry$1 = z.infer<typeof repoEntrySchema$1>;
+
+declare const DSN_ENV_VAR = "HIVENET_DSN";
+declare const REGISTRY_ENV_VAR = "HIVENET_REGISTRY";
+declare const HOME_ENV_VAR = "HIVENET_HOME";
+declare const NO_TELEMETRY_ENV_VAR = "HIVENET_NO_TELEMETRY";
+/** Minimal environment contract accepted by Node, Bun, Deno, and edge adapters. */
+type EnvLike = Record<string, string | undefined>;
+declare function feedbackHomeDir(env?: EnvLike): string;
+declare function isTelemetryDisabled(extraOptOutEnvVars?: string[], env?: EnvLike): boolean;
+
+/** A vendor-configured source for a product session ID. */
+type SessionSource = {
+    key: string;
+    envVar: string;
+} | {
+    key: string;
+    dotenvFile: string;
+    dotenvKey?: string;
+};
+type CollectContextOptions = {
+    projectRoot?: string;
+    sessions?: SessionSource[];
+    /** Vendor product fingerprint (versions, config). Never allowed to throw the pipeline. */
+    fingerprint?: () => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+    extraOptOutEnvVars?: string[];
+    env?: EnvLike;
+};
+/**
+ * Assemble best-effort context. Returns undefined when telemetry is disabled.
+ * Never throws; every block is optional.
+ */
+declare function collectContext(options?: CollectContextOptions): Promise<FeedbackContext$1 | undefined>;
+/** `agent` when an agent harness is detected, otherwise unknown (omitted). */
+declare function inferAuthor(context: FeedbackContext$1 | undefined): 'agent' | undefined;
+
+type Destination = {
+    endpoint: string;
+    writeKey?: string;
+    /** Tenant slug or domain, when known. */
+    to?: string;
+    descriptor?: Descriptor$1;
+};
+/** Shape of feedback.config.json — a local descriptor plus client-side settings. */
+type FeedbackConfig = {
+    name?: string;
+    slug?: string;
+    endpoint?: string;
+    writeKey?: string;
+    categories?: Descriptor$1['categories'];
+    sessions?: SessionSource[];
+    telemetryOptOutEnv?: string[];
+};
+declare const CONFIG_FILE_NAME = "feedback.config.json";
+type FetchLike = typeof fetch;
+type ResolveDestinationOptions = {
+    to?: string;
+    dsn?: string;
+    cwd?: string;
+    env?: EnvLike;
+    fetchImpl?: FetchLike;
+    /** Directory for the descriptor cache; defaults to the hivenet home dir. */
+    cacheDir?: string;
+};
+/**
+ * Parse a DSN: `https://hv_pub_KEY@host[/slug]`.
+ * One string carries endpoint + tenant + write key (the Sentry move).
+ */
+declare function parseDsn(dsn: string): Destination;
+/** Walk up from `startDir` looking for feedback.config.json. */
+declare function findConfigFile(startDir: string): {
+    config: FeedbackConfig;
+    path: string;
+} | undefined;
+declare function registryUrl(env?: EnvLike): string;
+/**
+ * Resolve where feedback goes. Priority:
+ * explicit DSN → HIVENET_DSN → nearest feedback.config.json →
+ * --to slug (hosted registry) / --to domain (.well-known).
+ */
+declare function resolveDestination(options?: ResolveDestinationOptions): Promise<Destination>;
+
+/** Configuration or validation error — the caller can fix it. Network failures are not
+ * FeedbackErrors; they degrade to the outbox instead of throwing. */
+declare class FeedbackError extends Error {
+    constructor(message: string);
+}
+
+type OutboxEntry = {
+    endpoint: string;
+    writeKey?: string;
+    event: FeedbackEvent$1;
+    queuedAt: string;
+};
+declare function outboxPath(env?: EnvLike): string;
+/** Queue an event that could not be delivered. Never throws — losing feedback is
+ * acceptable, breaking the host process is not. */
+declare function appendToOutbox(entry: OutboxEntry, env?: EnvLike): boolean;
+type FlushResult = {
+    delivered: number;
+    remaining: number;
+};
+/** Best-effort redelivery of queued events. Short timeout, never throws. */
+declare function flushOutbox(options?: {
+    env?: EnvLike;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<FlushResult>;
+
+type OwnerIssue = {
+    id: string;
+    title: string;
+    summary: string | null;
+    status: IssueStatus;
+    fingerprint: string | null;
+    event_count: number;
+    reopened_count: number;
+    first_seen: string;
+    last_seen: string;
+    links_json: string;
+};
+type OwnerEvent = {
+    id: string;
+    received_at: string;
+    status: EventStatus;
+    category: string;
+    subject: string | null;
+    sentiment: string | null;
+    author: string | null;
+    feedback: string;
+    agent_id: string | null;
+    agent_session: string | null;
+    thread_id: string;
+    consent_telemetry: number;
+    triage_note: string | null;
+    triaged_at: string | null;
+    issue_id: string | null;
+    links_json: string;
+    context_json: string;
+    metadata_json: string;
+    idempotency_key: string | null;
+};
+type OwnerFilters = {
+    status?: EventStatus;
+    category?: string;
+    thread?: string;
+    /** ISO timestamp — only events received at or after this moment ("what's new since my last run"). */
+    since?: string;
+    limit?: number;
+};
+type OwnerApiOptions = {
+    secretKey: string;
+    /** API origin, e.g. https://hivenet.app. */
+    apiOrigin?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+/** Derive the owner API origin from a slug/domain/DSN (same host as the ingest endpoint). */
+declare function resolveApiOrigin(options: {
+    to?: string;
+    dsn?: string;
+    env?: EnvLike;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+declare function ownerApi(options: OwnerApiOptions): {
+    listFeedback(filters?: OwnerFilters): Promise<{
+        project: string;
+        repos: RepoEntry$1[];
+        events: OwnerEvent[];
+    }>;
+    getFeedback(id: string): Promise<{
+        event: OwnerEvent;
+    }>;
+    setFeedbackStatus(id: string, status: EventStatus, note?: string): Promise<{
+        event: OwnerEvent;
+    }>;
+    listIssues(filters?: {
+        status?: IssueStatus;
+        since?: string;
+        limit?: number;
+    }): Promise<{
+        project: string;
+        repos: RepoEntry$1[];
+        issues: OwnerIssue[];
+    }>;
+    getIssue(id: string): Promise<{
+        issue: OwnerIssue;
+        repos: RepoEntry$1[];
+        events: OwnerEvent[];
+    }>;
+    setIssueStatus(id: string, status: IssueStatus, note?: string): Promise<{
+        issue: OwnerIssue;
+    }>;
+    /** Attach an external link (Slack message, Linear/GitHub issue, PR) to evt_… or iss_…. */
+    addLink(id: string, url: string, label?: string): Promise<{
+        event?: OwnerEvent;
+        issue?: OwnerIssue;
+    }>;
+};
+type OwnerApi = ReturnType<typeof ownerApi>;
+
+declare function generateThreadId(): string;
+/** A valid resume ID continues its thread; anything else gets a fresh one. */
+declare function resolveThreadId(resume?: string): {
+    id: string;
+    resumed: boolean;
+};
+type SendFeedbackOptions = {
+    feedback: string;
+    to?: string;
+    dsn?: string;
+    category?: string;
+    subject?: string;
+    sentiment?: Sentiment$1;
+    author?: FeedbackAuthor$1;
+    eval?: EvalReport$1;
+    /** Resume an existing feedback thread by ID. */
+    resume?: string;
+    /** Extra product session IDs, merged over detected ones. */
+    session?: Record<string, string>;
+    /** Vendor product fingerprint, merged into context.project. */
+    project?: Record<string, unknown>;
+    /** Vendor-defined enrichment (sdk_version, plan, build) — flat map, see spec metadataSchema. */
+    metadata?: FeedbackMetadata$1;
+    /** Override the auto-minted retry key (same key + project = same stored event). */
+    idempotencyKey?: string;
+    cwd?: string;
+    timeoutMs?: number;
+    /** Identify the embedding client (e.g. a vendor CLI) instead of the generic one. */
+    clientName?: string;
+    clientVersion?: string;
+    /** Set false to skip all context detection regardless of consent env vars. */
+    collectContext?: boolean;
+    /** Set false to fail without queueing when the endpoint is unreachable. */
+    outbox?: boolean;
+    contextOptions?: CollectContextOptions;
+    fetchImpl?: typeof fetch;
+    env?: EnvLike;
+};
+type SendFeedbackResult = {
+    delivered: true;
+    response: IngestResponse$1;
+    event: FeedbackEvent$1;
+    destination: Destination;
+    resumed: boolean;
+} | {
+    delivered: false;
+    queued: boolean;
+    error: string;
+    event: FeedbackEvent$1;
+    destination: Destination;
+    resumed: boolean;
+};
+/**
+ * Build, enrich, validate, and deliver one feedback event.
+ *
+ * Throws FeedbackError only for caller-fixable problems (no destination, invalid
+ * input). Network failures never throw: the event is queued to the outbox and
+ * `{ delivered: false, queued: true }` is returned.
+ */
+declare function sendFeedback(options: SendFeedbackOptions): Promise<SendFeedbackResult>;
+
+type PostEventOptions = {
+    endpoint: string;
+    writeKey?: string;
+    event: FeedbackEvent$1;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+};
+type PostEventResult = {
+    kind: 'accepted';
+    response: IngestResponse$1;
+} | {
+    kind: 'rejected';
+    status: number;
+    errors: string[];
+} | {
+    kind: 'unreachable';
+    error: string;
+};
+/** One POST, bounded by timeout. 4xx = rejected (do not retry); network/5xx = unreachable
+ * (outbox-eligible). */
+declare function postEvent(options: PostEventOptions): Promise<PostEventResult>;
+
+/**
+ * hivenet protocol v1.
+ *
+ * Everything here is the wire contract shared by the CLI, embeddable SDK, MCP tool,
+ * and any ingest endpoint (hosted or self-hosted). See SPEC.md for prose.
+ */
+declare const PROTOCOL_VERSION: 1;
+declare const MAX_FEEDBACK_LENGTH = 5000;
+declare const MAX_SUBJECT_LENGTH = 500;
+declare const MAX_GUIDANCE_LENGTH = 1000;
+declare const WELL_KNOWN_PATH = "/.well-known/agent-feedback.json";
+declare const DEFAULT_REGISTRY_URL = "https://hivenet.app";
+declare const DEFAULT_INGEST_PATH = "/v1/feedback";
+declare const WRITE_KEY_HEADER = "x-af-write-key";
+declare const WRITE_KEY_PATTERN: RegExp;
+declare const THREAD_ID_PATTERN: RegExp;
+/** Component kinds of any agentic system's agent-facing surface area. */
+declare const FEEDBACK_CATEGORIES: readonly ["tool", "skill", "prompt", "docs", "mcp", "cli", "api", "model", "eval", "ux", "other"];
+type FeedbackCategory = (typeof FEEDBACK_CATEGORIES)[number];
+declare const categorySchema: z.ZodUnion<readonly [z.ZodEnum<{
+    tool: "tool";
+    skill: "skill";
+    prompt: "prompt";
+    docs: "docs";
+    mcp: "mcp";
+    cli: "cli";
+    api: "api";
+    model: "model";
+    eval: "eval";
+    ux: "ux";
+    other: "other";
+}>, z.ZodString]>;
+declare const sentimentSchema: z.ZodEnum<{
+    positive: "positive";
+    negative: "negative";
+    neutral: "neutral";
+}>;
+type Sentiment = z.infer<typeof sentimentSchema>;
+/** Who authored the feedback text (cf. Arize Phoenix `annotator_kind`). */
+declare const authorSchema: z.ZodEnum<{
+    agent: "agent";
+    human: "human";
+    hybrid: "hybrid";
+}>;
+type FeedbackAuthor = z.infer<typeof authorSchema>;
+/**
+ * Structured failed-task report. `category: "eval"` events carry one of these so the
+ * feedback stream doubles as a replayable eval-candidate corpus.
+ */
+declare const evalReportSchema: z.ZodObject<{
+    task: z.ZodString;
+    expected: z.ZodOptional<z.ZodString>;
+    actual: z.ZodOptional<z.ZodString>;
+    mistake: z.ZodOptional<z.ZodString>;
+    attempts: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type EvalReport = z.infer<typeof evalReportSchema>;
+/**
+ * Auto-detected context. Every block is optional and best-effort: a missing block means
+ * "not detected or telemetry declined", never an error.
+ */
+declare const feedbackContextSchema: z.ZodObject<{
+    agent: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    ci: z.ZodOptional<z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        isPr: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    runtime: z.ZodOptional<z.ZodObject<{
+        platform: z.ZodString;
+        arch: z.ZodString;
+        node: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    project: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    session: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    user: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        authType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type FeedbackContext = z.infer<typeof feedbackContextSchema>;
+/**
+ * Vendor-defined enrichment (sdk_version, plan tier, build number). Flat by
+ * design — values stay renderable as chips and queryable via json_extract.
+ * Distinct from `context`, which is what the client auto-detects.
+ */
+declare const metadataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+type FeedbackMetadata = z.infer<typeof metadataSchema>;
+declare const feedbackEventSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    to: z.ZodOptional<z.ZodString>;
+    feedback: z.ZodString;
+    category: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+        tool: "tool";
+        skill: "skill";
+        prompt: "prompt";
+        docs: "docs";
+        mcp: "mcp";
+        cli: "cli";
+        api: "api";
+        model: "model";
+        eval: "eval";
+        ux: "ux";
+        other: "other";
+    }>, z.ZodString]>>;
+    subject: z.ZodOptional<z.ZodString>;
+    sentiment: z.ZodOptional<z.ZodEnum<{
+        positive: "positive";
+        negative: "negative";
+        neutral: "neutral";
+    }>>;
+    author: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
+        human: "human";
+        hybrid: "hybrid";
+    }>>;
+    thread: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    eval: z.ZodOptional<z.ZodObject<{
+        task: z.ZodString;
+        expected: z.ZodOptional<z.ZodString>;
+        actual: z.ZodOptional<z.ZodString>;
+        mistake: z.ZodOptional<z.ZodString>;
+        attempts: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodObject<{
+        agent: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        ci: z.ZodOptional<z.ZodObject<{
+            name: z.ZodNullable<z.ZodString>;
+            isPr: z.ZodNullable<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        runtime: z.ZodOptional<z.ZodObject<{
+            platform: z.ZodString;
+            arch: z.ZodString;
+            node: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        project: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        session: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        user: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            authType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    client: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>;
+    consent: z.ZodObject<{
+        telemetry: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type FeedbackEvent = z.infer<typeof feedbackEventSchema>;
+type FeedbackEventInput = z.input<typeof feedbackEventSchema>;
+/** 202 body returned by every conforming ingest endpoint. */
+declare const ingestResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    thread: z.ZodString;
+    resume: z.ZodOptional<z.ZodString>;
+    guidance: z.ZodOptional<z.ZodString>;
+    duplicate: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type IngestResponse = z.infer<typeof ingestResponseSchema>;
+/**
+ * Tenant descriptor. Served identically by the hosted registry
+ * (`{registry}/v1/registry/{slug}`) and by self-published well-known files
+ * (`https://{domain}/.well-known/agent-feedback.json`).
+ */
+declare const descriptorSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    name: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodURL;
+    writeKey: z.ZodOptional<z.ZodString>;
+    categories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        subject: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    jwks: z.ZodOptional<z.ZodURL>;
+    docs: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+type Descriptor = z.infer<typeof descriptorSchema>;
+/**
+ * A codebase a project's feedback is about. Owner-plane wire contract: rides on
+ * every list/get response so a triage agent knows where to go fix things.
+ */
+declare const repoEntrySchema: z.ZodObject<{
+    url: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RepoEntry = z.infer<typeof repoEntrySchema>;
+declare const repoListSchema: z.ZodArray<z.ZodObject<{
+    url: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+type ValidationResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    errors: string[];
+};
+declare function validateFeedbackEvent(input: unknown): ValidationResult<FeedbackEvent>;
+declare function validateDescriptor(input: unknown): ValidationResult<Descriptor>;
+declare function validateIngestResponse(input: unknown): ValidationResult<IngestResponse>;
+/** JSON Schema exports for non-TypeScript implementers. */
+declare function feedbackEventJsonSchema(): Record<string, unknown>;
+declare function descriptorJsonSchema(): Record<string, unknown>;
+
+export { CONFIG_FILE_NAME, type CollectContextOptions, DEFAULT_INGEST_PATH, DEFAULT_REGISTRY_URL, DSN_ENV_VAR, type Descriptor, type Destination, EVENT_STATUSES, type EnvLike, type EvalReport, type EventStatus, FEEDBACK_CATEGORIES, type FeedbackAuthor, type FeedbackCategory, type FeedbackConfig, type FeedbackContext, FeedbackError, type FeedbackEvent, type FeedbackEventInput, type FeedbackMetadata, type FlushResult, HOME_ENV_VAR, ISSUE_STATUSES, type IngestResponse, type IssueStatus, MAX_FEEDBACK_LENGTH, MAX_GUIDANCE_LENGTH, MAX_SUBJECT_LENGTH, NO_TELEMETRY_ENV_VAR, type OutboxEntry, type OwnerApi, type OwnerApiOptions, type OwnerEvent, type OwnerFilters, type OwnerIssue, PROTOCOL_VERSION, type PostEventOptions, type PostEventResult, REGISTRY_ENV_VAR, type RepoEntry, type ResolveDestinationOptions, type SendFeedbackOptions, type SendFeedbackResult, type Sentiment, type SessionSource, THREAD_ID_PATTERN, type ValidationResult, WELL_KNOWN_PATH, WRITE_KEY_HEADER, WRITE_KEY_PATTERN, appendToOutbox, authorSchema, categorySchema, collectContext, descriptorJsonSchema, descriptorSchema, evalReportSchema, feedbackContextSchema, feedbackEventJsonSchema, feedbackEventSchema, feedbackHomeDir, findConfigFile, flushOutbox, generateThreadId, inferAuthor, ingestResponseSchema, isTelemetryDisabled, metadataSchema, outboxPath, ownerApi, parseDsn, postEvent, registryUrl, repoEntrySchema, repoListSchema, resolveApiOrigin, resolveDestination, resolveThreadId, sendFeedback, sentimentSchema, validateDescriptor, validateFeedbackEvent, validateIngestResponse };