@crouton-kit/humanloop 0.3.39 → 0.4.0

package/dist/inbox/visual.d.ts

@@ -0,0 +1,130 @@
+import type { CanonicalInteraction, Interaction, VisualRequest as PanelVisualRequest } from '../types.js';
+import { type CompletionHandler } from './registry.js';
+export declare const VISUAL_CAPABILITY: "humanloop.visual/v1";
+export interface VisualClaimIdentity {
+    token: string;
+    host: string;
+    pid: number;
+    claimedAt: string;
+}
+export interface VisualCleanupObligation {
+    reason: 'canceled' | 'unreceipted_start_error';
+    attempts: number;
+    nextAttemptAt: string;
+    lastAttemptAt?: string;
+    lastError?: string;
+}
+interface VisualBinding {
+    capability: typeof VISUAL_CAPABILITY;
+    owner: string;
+    root: string;
+    dir: string;
+    ticketId: string;
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claim: VisualClaimIdentity;
+    handler: CompletionHandler;
+}
+export interface VisualProtocolRequest extends VisualBinding {
+    schema: 'humanloop.visual-request/v1';
+    state: 'running' | 'canceled' | 'terminal';
+    requestedAt: string;
+    settledAt?: string;
+    cleanup?: VisualCleanupObligation;
+}
+export interface VisualRequestEvent extends VisualBinding {
+    schema: 'humanloop.visual-request-event/v1';
+    action: 'start' | 'cancel';
+}
+interface VisualResultBinding extends VisualBinding {
+    schema: 'humanloop.visual-result/v1';
+    completedAt: string;
+}
+export type VisualProtocolResult = (VisualResultBinding & {
+    status: 'ready';
+    markdown: string;
+}) | (VisualResultBinding & {
+    status: 'error';
+    error: string;
+});
+export type VisualResultSubmission = {
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claimToken: string;
+    status: 'ready';
+    markdown: string;
+} | {
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claimToken: string;
+    status: 'error';
+    error: string;
+};
+export interface StartVisualRequestOptions {
+    root: string;
+    dir: string;
+    claimToken: string;
+    request: PanelVisualRequest;
+}
+export type VisualStartDeliveryResult = 'delivered' | 'already_attempted' | 'ineligible' | 'failed';
+export type VisualCleanupDeliveryResult = 'delivered' | 'pending' | 'none';
+export interface StartedVisualRequest {
+    request: VisualProtocolRequest;
+    /** Resolves after the one permitted start attempt reaches a determinate outcome. */
+    delivery: Promise<VisualStartDeliveryResult>;
+}
+export interface VisualCleanupTask {
+    root: string;
+    dir: string;
+    requestId: string;
+    reason: VisualCleanupObligation['reason'];
+    nextAttemptAt: string;
+}
+/** Normalize one Interaction into the sole persisted/event correlation shape. */
+export declare function canonicalizeInteraction(raw: Interaction | CanonicalInteraction): CanonicalInteraction;
+/** Stable bytes used for every interaction equality check across the protocol. */
+export declare function canonicalInteractionJson(raw: Interaction | CanonicalInteraction): string;
+export declare function parseVisualRequestEvent(raw: unknown): VisualRequestEvent;
+/** Strict, repairing reader; malformed or unbound request bytes return null. */
+export declare function readVisualRequest(root: string, dir: string, requestId: string): VisualProtocolRequest | null;
+/** Strict, repairing reader; canceled and mismatched results are never returned. */
+export declare function readVisualResult(root: string, dir: string, requestId: string): VisualProtocolResult | null;
+/** Decode an event and atomically bind it to Humanloop's immutable request state. */
+export declare function readVisualRequestForEvent(raw: unknown): VisualProtocolRequest | null;
+/** Persist one claim-bound request and dispatch its frozen handler at most once. */
+export declare function startVisualRequest(opts: StartVisualRequestOptions): StartedVisualRequest;
+/** Compare-publish the first fully correlated ready/error result. Stale writers are no-ops. */
+export declare function submitVisualResult(root: string, dir: string, raw: VisualResultSubmission): {
+    published: boolean;
+};
+/** Attempt one due cleanup delivery through the request's frozen handler. */
+export declare function dispatchVisualCleanup(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
+/** State-first cancellation for one handle; the returned promise is cleanup delivery only. */
+export declare function cancelVisualRequest(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
+/** State-first cancel every running request, then dispatch every owed cleanup (including start failures). */
+export declare function cancelVisualRequestsForTicket(root: string, dir: string): Promise<{
+    canceled: number;
+    cleanupOwed: number;
+}>;
+/** Durable tasks the next controller-owned retry executor should schedule. */
+export declare function listVisualCleanupObligations(root: string, dir: string): VisualCleanupTask[];
+export interface VisualRequestReconciliation {
+    retired: number;
+    cleanupOwed: number;
+    /** Cleanup delivery only; reconciliation never redelivers a start. */
+    delivery: Promise<VisualCleanupDeliveryResult[]>;
+}
+/** Retire abandoned generations under the ticket claim boundary. A live claim is
+ * authoritative; a newly acquired claim retires every older generation first. */
+export declare function reconcileVisualRequestsForTicket(root: string, dir: string, currentClaimToken?: string): VisualRequestReconciliation;
+/** Enumerate direct ticket children only, including resolved tickets whose cleanup is still owed. */
+export declare function listVisualCleanupObligationsForRoot(root: string): VisualCleanupTask[];
+/** Startup reconciliation only retires stale/missing-claim work; live owners stay untouched. */
+export declare function reconcileStaleVisualRequestsForRoot(root: string): VisualRequestReconciliation[];
+export {};