hivenet 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -0,0 +1,1053 @@
+import { z } from 'zod';
+
+declare const attachmentTargetSchema$1: z.ZodObject<{
+    type: z.ZodEnum<{
+        eval: "eval";
+        question: "question";
+        event: "event";
+        issue: "issue";
+        investigation: "investigation";
+        investigation_question: "investigation_question";
+        investigation_reply: "investigation_reply";
+    }>;
+    id: z.ZodString;
+}, z.core.$strip>;
+type AttachmentTarget$1 = z.infer<typeof attachmentTargetSchema$1>;
+declare const attachmentSchema$1: z.ZodObject<{
+    filename: z.ZodString;
+    mediaType: z.ZodString;
+    size: z.ZodNumber;
+    sha256: z.ZodString;
+    id: z.ZodString;
+    createdAt: z.ZodString;
+    source: z.ZodEnum<{
+        reporter: "reporter";
+        owner: "owner";
+    }>;
+    uploader: z.ZodNullable<z.ZodString>;
+    target: z.ZodObject<{
+        type: z.ZodEnum<{
+            eval: "eval";
+            question: "question";
+            event: "event";
+            issue: "issue";
+            investigation: "investigation";
+            investigation_question: "investigation_question";
+            investigation_reply: "investigation_reply";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Attachment$1 = z.infer<typeof attachmentSchema$1>;
+/** 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", "needs_review", "resolved", "wont_fix", "spam"];
+declare const issueStatusSchema: z.ZodEnum<{
+    in_progress: "in_progress";
+    resolved: "resolved";
+    wont_fix: "wont_fix";
+    spam: "spam";
+    open: "open";
+    needs_review: "needs_review";
+}>;
+type IssueStatus = z.infer<typeof issueStatusSchema>;
+/** Eval curation states: promoted candidates → accepted corpus → archived. */
+declare const EVAL_STATUSES: readonly ["proposed", "accepted", "archived"];
+type EvalStatus = (typeof EVAL_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";
+        ux: "ux";
+        other: "other";
+    }>, z.ZodEnum<{
+        eval: "eval";
+    }>, 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>>;
+    question: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        token: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, 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>;
+/** The existing owner SDK's issue projection; distinct from reporter-visible KnownIssue. */
+declare const ownerIssueSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        in_progress: "in_progress";
+        resolved: "resolved";
+        wont_fix: "wont_fix";
+        spam: "spam";
+        open: "open";
+        needs_review: "needs_review";
+    }>;
+    fingerprint: z.ZodNullable<z.ZodString>;
+    event_count: z.ZodNumber;
+    reopened_count: z.ZodNumber;
+    first_seen: z.ZodString;
+    last_seen: z.ZodString;
+    links_json: z.ZodString;
+}, z.core.$strip>;
+type OwnerIssue = z.infer<typeof ownerIssueSchema>;
+/** 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>;
+    known_issue: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            wont_fix: "wont_fix";
+            open: "open";
+        }>;
+        reopened: z.ZodOptional<z.ZodBoolean>;
+        reports: z.ZodNumber;
+        note: z.ZodOptional<z.ZodString>;
+        hint: z.ZodString;
+    }, z.core.$strip>>;
+    ask: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        prompt: z.ZodString;
+        command: z.ZodString;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            filename: z.ZodString;
+            mediaType: z.ZodString;
+            size: z.ZodNumber;
+            sha256: z.ZodString;
+            id: z.ZodString;
+            createdAt: z.ZodString;
+            source: z.ZodEnum<{
+                reporter: "reporter";
+                owner: "owner";
+            }>;
+            uploader: z.ZodNullable<z.ZodString>;
+            target: z.ZodObject<{
+                type: z.ZodEnum<{
+                    eval: "eval";
+                    question: "question";
+                    event: "event";
+                    issue: "issue";
+                    investigation: "investigation";
+                    investigation_question: "investigation_question";
+                    investigation_reply: "investigation_reply";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strip>;
+            description: z.ZodOptional<z.ZodString>;
+            url: z.ZodURL;
+            expiresAt: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    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>;
+
+/** 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 LocalAttachmentInput = string | {
+    path: string;
+    description?: string;
+};
+
+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>;
+
+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 OwnerEvent = {
+    id: string;
+    received_at: string;
+    status: EventStatus;
+    category: string;
+    subject: string | null;
+    sentiment: string | null;
+    author: string | null;
+    feedback: string;
+    /** Detector slug of the reporting agent ('claude-code', 'codex'). */
+    agent: 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 OwnerQuestion = {
+    id: string;
+    prompt: string;
+    source: 'owner' | 'system';
+    kind: 'research' | 'verify_fix' | 'setup_request';
+    status: 'active' | 'closed';
+    created_at: string;
+    closed_at: string | null;
+    target: {
+        category?: string;
+        issue_id?: string;
+        eval_id?: string;
+        thread_id?: string;
+    };
+    answers: {
+        id: string;
+        feedback: string;
+        agent: string | null;
+        client_name: string | null;
+        received_at: string;
+    }[];
+};
+type OwnerEval = {
+    id: string;
+    title: string;
+    task: string;
+    expected: string | null;
+    setup: string | null;
+    status: EvalStatus;
+    note: string | null;
+    source_event_id: string | null;
+    created_at: string;
+    updated_at: string;
+    source: {
+        event_id: string;
+        feedback: string;
+        agent: string | null;
+        client_name: string | null;
+        thread_id: string;
+        actual: string | null;
+        mistake: string | null;
+        attempts: number | null;
+    } | null;
+    /** Active setup_request question id when reproduction state is still missing. */
+    setup_pending: 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): {
+    /** Upload local files and attach them to a record (at most 10 files per record). */
+    attachFiles(target: AttachmentTarget$1, paths: LocalAttachmentInput[], cwd?: string): Promise<{
+        attachments: Attachment$1[];
+    }>;
+    /** A record's files; issues and evals include their reports' files. */
+    listAttachments(target: AttachmentTarget$1, offset?: number): Promise<{
+        attachments: Attachment$1[];
+        nextOffset: number | null;
+    }>;
+    deleteAttachment(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    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;
+    }>;
+    listQuestions(filters?: {
+        status?: "active" | "closed";
+    }): Promise<{
+        questions: OwnerQuestion[];
+        /** True when the bounded answer window dropped older answers. */
+        answers_truncated: boolean;
+    }>;
+    /** Files are shared with every agent that receives the question. */
+    createQuestion(prompt: string, category?: string, options?: {
+        files?: LocalAttachmentInput[];
+        cwd?: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        question: OwnerQuestion;
+    }>;
+    closeQuestion(id: string): Promise<{
+        closed: boolean;
+        id: string;
+    }>;
+    listEvals(filters?: {
+        status?: EvalStatus;
+    }): Promise<{
+        evals: OwnerEval[];
+    }>;
+    getEval(id: string): Promise<{
+        eval: OwnerEval;
+    }>;
+    /** Promote a failed-task report (category=eval event) into the eval corpus. */
+    promoteEval(eventId: string): Promise<{
+        eval: OwnerEval;
+        created: boolean;
+    }>;
+    setEvalStatus(id: string, status: EvalStatus, note?: string): Promise<{
+        eval: OwnerEval;
+    }>;
+    /** 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;
+    /** Id of a question this submission answers (from a prior response's `ask`). */
+    question?: string;
+    /** Explicit paths with optional context. Paths stay local; basenames, bytes and descriptions are sent. */
+    attachments?: LocalAttachmentInput[];
+    /** 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;
+};
+/** Files that could not be uploaded; the report went (or was queued) without them. */
+type FilesNotAttached = {
+    files: string[];
+    reason: string;
+};
+type SendFeedbackResult = {
+    delivered: true;
+    response: IngestResponse$1;
+    event: FeedbackEvent$1;
+    destination: Destination;
+    resumed: boolean;
+    filesNotAttached?: FilesNotAttached;
+} | {
+    delivered: false;
+    queued: boolean;
+    error: string;
+    event: FeedbackEvent$1;
+    destination: Destination;
+    resumed: boolean;
+    filesNotAttached?: FilesNotAttached;
+};
+/**
+ * Build, enrich, validate, and deliver one feedback event.
+ *
+ * Throws FeedbackError only for caller-fixable problems (no destination, invalid
+ * input, a file the server rejects). Network failures never throw: the event is
+ * queued to the outbox and `{ delivered: false, queued: true }` is returned.
+ * Selected files upload first; if they can't be (network, server busy, a server
+ * without file storage), the report still goes — or is queued — without them, and
+ * `filesNotAttached` says so.
+ */
+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, 408 and 429 =
+ * unreachable (outbox-eligible). */
+declare function postEvent(options: PostEventOptions): Promise<PostEventResult>;
+
+declare const MAX_ATTACHMENT_BYTES: number;
+declare const MAX_ATTACHMENTS = 10;
+declare const attachmentTargetSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        eval: "eval";
+        question: "question";
+        event: "event";
+        issue: "issue";
+        investigation: "investigation";
+        investigation_question: "investigation_question";
+        investigation_reply: "investigation_reply";
+    }>;
+    id: z.ZodString;
+}, z.core.$strip>;
+type AttachmentTarget = z.infer<typeof attachmentTargetSchema>;
+declare const attachmentSchema: z.ZodObject<{
+    filename: z.ZodString;
+    mediaType: z.ZodString;
+    size: z.ZodNumber;
+    sha256: z.ZodString;
+    id: z.ZodString;
+    createdAt: z.ZodString;
+    source: z.ZodEnum<{
+        reporter: "reporter";
+        owner: "owner";
+    }>;
+    uploader: z.ZodNullable<z.ZodString>;
+    target: z.ZodObject<{
+        type: z.ZodEnum<{
+            eval: "eval";
+            question: "question";
+            event: "event";
+            issue: "issue";
+            investigation: "investigation";
+            investigation_question: "investigation_question";
+            investigation_reply: "investigation_reply";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Attachment = z.infer<typeof attachmentSchema>;
+/** Question files as delivered to reporting agents, with a short-lived read link. */
+declare const deliveredAttachmentSchema: z.ZodObject<{
+    filename: z.ZodString;
+    mediaType: z.ZodString;
+    size: z.ZodNumber;
+    sha256: z.ZodString;
+    id: z.ZodString;
+    createdAt: z.ZodString;
+    source: z.ZodEnum<{
+        reporter: "reporter";
+        owner: "owner";
+    }>;
+    uploader: z.ZodNullable<z.ZodString>;
+    target: z.ZodObject<{
+        type: z.ZodEnum<{
+            eval: "eval";
+            question: "question";
+            event: "event";
+            issue: "issue";
+            investigation: "investigation";
+            investigation_question: "investigation_question";
+            investigation_reply: "investigation_reply";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    description: z.ZodOptional<z.ZodString>;
+    url: z.ZodURL;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+type DeliveredAttachment = z.infer<typeof deliveredAttachmentSchema>;
+
+/**
+ * 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. Categories answer
+ * "what part of the product is this about?" — kinds of submission (failed-task reports,
+ * question answers) are orthogonal markers (`eval` block, `question` id), never categories.
+ */
+declare const FEEDBACK_CATEGORIES: readonly ["tool", "skill", "prompt", "docs", "mcp", "cli", "api", "model", "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";
+    ux: "ux";
+    other: "other";
+}>, z.ZodEnum<{
+    eval: "eval";
+}>, 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";
+        ux: "ux";
+        other: "other";
+    }>, z.ZodEnum<{
+        eval: "eval";
+    }>, 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>>;
+    question: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        token: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, 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>;
+    known_issue: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            wont_fix: "wont_fix";
+            open: "open";
+        }>;
+        reopened: z.ZodOptional<z.ZodBoolean>;
+        reports: z.ZodNumber;
+        note: z.ZodOptional<z.ZodString>;
+        hint: z.ZodString;
+    }, z.core.$strip>>;
+    ask: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        prompt: z.ZodString;
+        command: z.ZodString;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            filename: z.ZodString;
+            mediaType: z.ZodString;
+            size: z.ZodNumber;
+            sha256: z.ZodString;
+            id: z.ZodString;
+            createdAt: z.ZodString;
+            source: z.ZodEnum<{
+                reporter: "reporter";
+                owner: "owner";
+            }>;
+            uploader: z.ZodNullable<z.ZodString>;
+            target: z.ZodObject<{
+                type: z.ZodEnum<{
+                    eval: "eval";
+                    question: "question";
+                    event: "event";
+                    issue: "issue";
+                    investigation: "investigation";
+                    investigation_question: "investigation_question";
+                    investigation_reply: "investigation_reply";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strip>;
+            description: z.ZodOptional<z.ZodString>;
+            url: z.ZodURL;
+            expiresAt: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    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 { type Attachment, type AttachmentTarget, CONFIG_FILE_NAME, type CollectContextOptions, DEFAULT_INGEST_PATH, DEFAULT_REGISTRY_URL, DSN_ENV_VAR, type DeliveredAttachment, 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 FilesNotAttached, type FlushResult, HOME_ENV_VAR, ISSUE_STATUSES, type IngestResponse, type IssueStatus, type LocalAttachmentInput, MAX_ATTACHMENTS, MAX_ATTACHMENT_BYTES, 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 };