@o11y-one/sdk 0.0.0

package/dist/evaluation.js

@@ -0,0 +1,455 @@
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { AgenticEvaluationService, MachinePrincipalScopeV1, PlatformAnnotationKindV1, EvaluationLaunchRejectionV1Schema, EvaluationCaptureRefusalV1Schema, EvaluationDatasetVersionRejectionV1Schema, PlatformAnnotationRejectionV1Schema, } from "@o11y-one/api-agentic/o11y_one/agentic/v1/evaluation_pb";
+import { ok, err } from "./result.js";
+import { findDetail, toLaunchRejection, toCaptureRefusal, toDatasetVersionRejection, toAnnotationRejection, toLeaseRefusal, toCaseAck, toCursorResync, } from "./refusals.js";
+import { requireNonEmpty, requireIdempotencyKey, requireExactlyOne, rejectUnspecified, } from "./validate.js";
+// --- scope vocabulary bridge ------------------------------------------------
+// The five canonical scope strings (errors.ts, frozen taxonomy) <-> the proto's
+// numeric MachinePrincipalScopeV1. Callers speak strings; the wire speaks the
+// enum; neither leaks into the other.
+const SCOPE_TO_ENUM = {
+    "eval:read": MachinePrincipalScopeV1.EVAL_READ,
+    "run:execute": MachinePrincipalScopeV1.RUN_EXECUTE,
+    "dataset:write": MachinePrincipalScopeV1.DATASET_WRITE,
+    "lease:submit": MachinePrincipalScopeV1.LEASE_SUBMIT,
+    "platform-annotation:write": MachinePrincipalScopeV1.PLATFORM_ANNOTATION_WRITE,
+};
+const ENUM_TO_SCOPE = {
+    [MachinePrincipalScopeV1.EVAL_READ]: "eval:read",
+    [MachinePrincipalScopeV1.RUN_EXECUTE]: "run:execute",
+    [MachinePrincipalScopeV1.DATASET_WRITE]: "dataset:write",
+    [MachinePrincipalScopeV1.LEASE_SUBMIT]: "lease:submit",
+    [MachinePrincipalScopeV1.PLATFORM_ANNOTATION_WRITE]: "platform-annotation:write",
+};
+/** Canonical scope strings for a set of wire discriminants; UNSPECIFIED drops. */
+export function scopesToCanonical(values) {
+    const out = [];
+    for (const v of values) {
+        const s = ENUM_TO_SCOPE[v];
+        if (s !== undefined) {
+            out.push(s);
+        }
+    }
+    return out;
+}
+// --- one-time credential material -------------------------------------------
+/**
+ * The plaintext credential returned exactly once by `createMachineCredential`.
+ *
+ * It is a DISTINCT type the caller must consume deliberately: `reveal()` hands
+ * over the string, and every accidental-logging path — `toString`,
+ * `toJSON`, Node's `util.inspect` — returns a redaction instead. The server
+ * keeps no read-back copy, so this object is the only place the material ever
+ * exists; the redaction is there so a stray `console.log(result)` cannot leak
+ * it into a CI log.
+ */
+export class OneTimeCredential {
+    #plaintext;
+    /** The credential-id this token belongs to, safe to log. */
+    credentialId;
+    constructor(plaintext, credentialId) {
+        this.#plaintext = plaintext;
+        this.credentialId = credentialId;
+    }
+    /** Hand over the plaintext. Store it in your secret manager; never log it. */
+    reveal() {
+        return this.#plaintext;
+    }
+    toString() {
+        return "[o11y one-time credential — redacted; call reveal()]";
+    }
+    toJSON() {
+        return "[o11y one-time credential — redacted]";
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toString();
+    }
+}
+// --- the client -------------------------------------------------------------
+export class AgenticEvaluationClient {
+    raw;
+    constructor(client) {
+        this.raw = client.service(AgenticEvaluationService);
+    }
+    // -- 1. identity ----------------------------------------------------------
+    /**
+     * Answer "is my credential valid, and which scopes does it carry?" BEFORE a
+     * run. An UNAUTHENTICATED / PERMISSION_DENIED here is a thrown `ConnectError`
+     * the caller renders with `classify()`; a success carries the scope set that
+     * turns a minute-40 failure into a minute-0 one.
+     */
+    async whoami() {
+        const res = await this.raw.getCallerPrincipal({});
+        const scopes = scopesToCanonical(res.machinePrincipal?.scopes ?? []);
+        const scopeSet = new Set(scopes);
+        return {
+            tenantId: res.tenantId,
+            orgId: res.orgId,
+            machinePrincipalId: res.machinePrincipal?.machinePrincipalId,
+            credentialId: res.credential?.credentialId,
+            scopes,
+            hasScope: (scope) => scopeSet.has(scope),
+            raw: res,
+        };
+    }
+    // -- 2. machine credentials ----------------------------------------------
+    async createMachinePrincipal(args) {
+        requireNonEmpty("displayName", args.displayName);
+        const scopes = args.scopes.map((s) => SCOPE_TO_ENUM[s]);
+        rejectUnspecified("scopes", scopes);
+        const res = await this.raw.createMachinePrincipal({
+            displayName: args.displayName,
+            ...(args.description !== undefined ? { description: args.description } : {}),
+            scopes,
+        });
+        if (res.principal === undefined) {
+            throw new Error("createMachinePrincipal: server returned no principal");
+        }
+        return res.principal;
+    }
+    async listMachinePrincipals(args) {
+        const res = await this.raw.listMachinePrincipals({
+            ...(args?.pageSize !== undefined ? { pageSize: args.pageSize } : {}),
+            ...(args?.pageToken !== undefined ? { pageToken: args.pageToken } : {}),
+        });
+        return { principals: res.principals, nextPageToken: res.nextPageToken };
+    }
+    /**
+     * Mint a credential. The plaintext comes back once, wrapped in a
+     * {@link OneTimeCredential} the caller must `reveal()` to read and can never
+     * accidentally log.
+     */
+    async createMachineCredential(args) {
+        requireNonEmpty("machinePrincipalId", args.machinePrincipalId);
+        const res = await this.raw.createMachineCredential({
+            machinePrincipalId: args.machinePrincipalId,
+            ...(args.description !== undefined ? { description: args.description } : {}),
+            ...(args.expiresAt !== undefined ? { expiresAt: timestampFromDate(args.expiresAt) } : {}),
+        });
+        if (res.credential === undefined) {
+            throw new Error("createMachineCredential: server returned no credential metadata");
+        }
+        return {
+            credential: res.credential,
+            token: new OneTimeCredential(res.plaintextTokenOnce, res.credential.credentialId),
+        };
+    }
+    async revokeMachineCredential(args) {
+        requireNonEmpty("credentialId", args.credentialId);
+        const res = await this.raw.revokeMachineCredential({
+            credentialId: args.credentialId,
+            ...(args.revokeReason !== undefined ? { revokeReason: args.revokeReason } : {}),
+        });
+        if (res.credential === undefined) {
+            throw new Error("revokeMachineCredential: server returned no credential");
+        }
+        return res.credential;
+    }
+    async revokeMachinePrincipal(args) {
+        requireNonEmpty("machinePrincipalId", args.machinePrincipalId);
+        const res = await this.raw.revokeMachinePrincipal({
+            machinePrincipalId: args.machinePrincipalId,
+            ...(args.revokeReason !== undefined ? { revokeReason: args.revokeReason } : {}),
+        });
+        if (res.principal === undefined) {
+            throw new Error("revokeMachinePrincipal: server returned no principal");
+        }
+        return { principal: res.principal, revokedCredentials: res.revokedCredentials };
+    }
+    // -- 3. run submission ----------------------------------------------------
+    /**
+     * Resolve and freeze what a launch WOULD do: the preview token, its digest
+     * and expiry, the frozen manifest, the estimates and any blockers. Launch
+     * from the token this returns.
+     *
+     * NOTE: the wire contract launches from a definition (+ optional revision)
+     * through a preview token; there is no inline-draft launch path in the proto
+     * at this capability. See l1-notes.
+     */
+    async previewRun(args) {
+        requireNonEmpty("definitionId", args.definitionId);
+        return await this.raw.previewEvaluationRun({
+            definitionId: args.definitionId,
+            ...(args.revisionId !== undefined ? { revisionId: args.revisionId } : {}),
+        });
+    }
+    /**
+     * Launch a run from an accepted preview token. Returns `err(LaunchRejection)`
+     * when a binding moved under the token (the refusal rides in `Status.details`
+     * on a FAILED_PRECONDITION); any other transport error rethrows.
+     */
+    async launchRun(args) {
+        requireNonEmpty("definitionId", args.definitionId);
+        requireIdempotencyKey("idempotencyKey", args.idempotencyKey);
+        requireNonEmpty("previewToken", args.previewToken);
+        try {
+            const res = await this.raw.createEvaluationRun({
+                definitionId: args.definitionId,
+                idempotencyKey: args.idempotencyKey,
+                previewToken: args.previewToken,
+            });
+            return ok(res);
+        }
+        catch (e) {
+            const detail = findDetail(e, EvaluationLaunchRejectionV1Schema);
+            if (detail !== undefined) {
+                return err(toLaunchRejection(detail));
+            }
+            throw e;
+        }
+    }
+    // -- 4/5. externally-executed loop: lease -> renew -> submit -> release ----
+    /**
+     * Claim a bounded set of prepared cases. `err(LeaseRefusal)` when the server
+     * refuses on a 200 (`SCOPE_MISSING`, `RUN_NOT_EXECUTABLE`, …). `ok` otherwise
+     * — and an `ok` with no lease is not a failure: check `exhausted`.
+     */
+    async leaseCases(args) {
+        requireNonEmpty("evaluationRunId", args.evaluationRunId);
+        requireNonEmpty("candidateKey", args.candidateKey);
+        requireNonEmpty("runtimeKey", args.runtimeKey);
+        const res = await this.raw.leaseEvaluationCases({
+            evaluationRunId: args.evaluationRunId,
+            candidateKey: args.candidateKey,
+            runtimeKey: args.runtimeKey,
+            maxCases: args.maxCases ?? 0,
+            leaseSeconds: args.leaseSeconds ?? 0,
+        });
+        if (res.refusal !== undefined) {
+            return err(toLeaseRefusal(res.refusal));
+        }
+        return ok({
+            lease: res.lease,
+            cases: res.cases,
+            remainingUnleasedCaseCount: res.remainingUnleasedCaseCount,
+            exhausted: res.lease === undefined && res.remainingUnleasedCaseCount === 0,
+        });
+    }
+    /** Heartbeat a held lease. `err(LeaseRefusal)` when the fence was lost. */
+    async renewLease(args) {
+        requireNonEmpty("evaluationRunId", args.evaluationRunId);
+        requireNonEmpty("leaseId", args.leaseId);
+        requireNonEmpty("leaseToken", args.leaseToken);
+        const res = await this.raw.renewEvaluationCaseLease({
+            evaluationRunId: args.evaluationRunId,
+            leaseId: args.leaseId,
+            leaseToken: args.leaseToken,
+            leaseSeconds: args.leaseSeconds ?? 0,
+        });
+        if (res.refusal !== undefined) {
+            return err(toLeaseRefusal(res.refusal));
+        }
+        if (res.lease === undefined) {
+            throw new Error("renewEvaluationCaseLease: neither lease nor refusal was returned");
+        }
+        return ok(res.lease);
+    }
+    /**
+     * Submit a batch of case outputs — the recorded-output upload and the
+     * external-loop submit are the same verb. Returns a {@link SubmissionOutcome}
+     * that partitions the batch: which coordinates landed, which were duplicates,
+     * which were rejected and why — never an all-or-nothing throw. A whole-request
+     * refusal (fence lost) appears as `outcome.refusal`, with no per-case answers.
+     *
+     * Idempotent by lease identity and coordinate: a resubmit of the same batch
+     * reports the landed cases as `ALREADY_SUBMITTED`.
+     */
+    async submitCaseOutputs(args) {
+        requireNonEmpty("evaluationRunId", args.evaluationRunId);
+        requireNonEmpty("leaseId", args.leaseId);
+        requireNonEmpty("leaseToken", args.leaseToken);
+        requireIdempotencyKey("idempotencyKey", args.idempotencyKey);
+        if (args.outputs.length === 0) {
+            requireNonEmpty("outputs", "");
+        }
+        const res = await this.raw.submitEvaluationCaseOutputs({
+            evaluationRunId: args.evaluationRunId,
+            leaseId: args.leaseId,
+            leaseToken: args.leaseToken,
+            outputs: args.outputs,
+            idempotencyKey: args.idempotencyKey,
+        });
+        const acks = res.acks.map(toCaseAck);
+        return {
+            acceptedCount: res.acceptedCount,
+            alreadySubmittedCount: res.alreadySubmittedCount,
+            rejectedCount: res.rejectedCount,
+            acks,
+            accepted: acks.filter((a) => a.kind === "ACCEPTED"),
+            alreadySubmitted: acks.filter((a) => a.kind === "ALREADY_SUBMITTED"),
+            rejected: acks.filter((a) => a.kind === "REJECTED"),
+            remainingLeasedCaseCount: res.remainingLeasedCaseCount,
+            refusal: res.refusal !== undefined ? toLeaseRefusal(res.refusal) : undefined,
+        };
+    }
+    /** Release a held lease early. `err(LeaseRefusal)` when the fence was lost. */
+    async releaseLease(args) {
+        requireNonEmpty("evaluationRunId", args.evaluationRunId);
+        requireNonEmpty("leaseId", args.leaseId);
+        requireNonEmpty("leaseToken", args.leaseToken);
+        const res = await this.raw.releaseEvaluationCaseLease({
+            evaluationRunId: args.evaluationRunId,
+            leaseId: args.leaseId,
+            leaseToken: args.leaseToken,
+        });
+        if (res.refusal !== undefined) {
+            return err(toLeaseRefusal(res.refusal));
+        }
+        return ok(res.releasedCaseCount);
+    }
+    // -- 6. dataset drafts: create / append / publish -------------------------
+    /**
+     * Create a dataset version from EXACTLY ONE ingest source: raw JSONL bytes, or
+     * a finalized capture draft by id. `err(DatasetVersionRejection)` on a typed
+     * ingest refusal (rides in `Status.details`); any other error rethrows.
+     */
+    async createDatasetVersion(args) {
+        requireIdempotencyKey("idempotencyKey", args.idempotencyKey);
+        requireExactlyOne("ingest", [
+            { name: "jsonl", present: args.jsonl !== undefined },
+            { name: "draftId", present: args.draftId !== undefined },
+        ]);
+        const ingest = args.jsonl !== undefined
+            ? { case: "jsonl", value: args.jsonl }
+            : { case: "draftId", value: args.draftId };
+        try {
+            const res = await this.raw.createEvaluationDatasetVersion({
+                ...(args.datasetCollectionId !== undefined
+                    ? { datasetCollectionId: args.datasetCollectionId }
+                    : {}),
+                ...(args.collectionName !== undefined ? { collectionName: args.collectionName } : {}),
+                ...(args.label !== undefined ? { label: args.label } : {}),
+                ingest,
+                ...(args.recordedOutputFieldPath !== undefined
+                    ? { recordedOutputFieldPath: args.recordedOutputFieldPath }
+                    : {}),
+                ...(args.expectedDraftVersion !== undefined
+                    ? { expectedDraftVersion: args.expectedDraftVersion }
+                    : {}),
+                idempotencyKey: args.idempotencyKey,
+            });
+            return ok(res);
+        }
+        catch (e) {
+            const detail = findDetail(e, EvaluationDatasetVersionRejectionV1Schema);
+            if (detail !== undefined) {
+                return err(toDatasetVersionRejection(detail));
+            }
+            throw e;
+        }
+    }
+    /**
+     * Append one case to a collection's open draft, from EXACTLY ONE source: a
+     * trace span or a matrix cell. `err(CaptureRefusal)` on a typed capture
+     * refusal (rides in `Status.details`).
+     */
+    async captureCase(args) {
+        requireNonEmpty("datasetCollectionId", args.datasetCollectionId);
+        requireIdempotencyKey("idempotencyKey", args.idempotencyKey);
+        requireExactlyOne("source", [
+            { name: "span", present: args.span !== undefined },
+            { name: "cell", present: args.cell !== undefined },
+        ]);
+        const source = args.span !== undefined
+            ? { case: "span", value: args.span }
+            : { case: "cell", value: args.cell };
+        try {
+            const res = await this.raw.captureEvaluationCase({
+                datasetCollectionId: args.datasetCollectionId,
+                ...(args.draftId !== undefined ? { draftId: args.draftId } : {}),
+                source,
+                fieldMappings: (args.fieldMappings ?? []),
+                ...(args.recordedOutputFieldPath !== undefined
+                    ? { recordedOutputFieldPath: args.recordedOutputFieldPath }
+                    : {}),
+                ...(args.baseDatasetVersionId !== undefined
+                    ? { baseDatasetVersionId: args.baseDatasetVersionId }
+                    : {}),
+                ...(args.expectedContentDigest !== undefined
+                    ? { expectedContentDigest: args.expectedContentDigest }
+                    : {}),
+                idempotencyKey: args.idempotencyKey,
+            });
+            return ok(res);
+        }
+        catch (e) {
+            const detail = findDetail(e, EvaluationCaptureRefusalV1Schema);
+            if (detail !== undefined) {
+                return err(toCaptureRefusal(detail));
+            }
+            throw e;
+        }
+    }
+    /**
+     * Publish a reviewed changeset. A digest mismatch is a FAILED_PRECONDITION
+     * transport error (never a silent rebase) and is thrown for `classify()`.
+     */
+    async publishDatasetDrafts(args) {
+        requireNonEmpty("changesetId", args.changesetId);
+        requireNonEmpty("previewDigest", args.previewDigest);
+        requireIdempotencyKey("idempotencyKey", args.idempotencyKey);
+        return await this.raw.publishDatasetCaseDrafts({
+            changesetId: args.changesetId,
+            previewDigest: args.previewDigest,
+            ...(args.label !== undefined ? { label: args.label } : {}),
+            idempotencyKey: args.idempotencyKey,
+        });
+    }
+    // -- 7. annotations -------------------------------------------------------
+    /**
+     * Record a deployment marker, custom event, or time-range highlight.
+     * `err(AnnotationRejection)` on a typed rejection (rides in `Status.details`).
+     * A `startAt`/`endAt` are `Date`s; omit `endAt` for an instant.
+     */
+    async recordAnnotation(args) {
+        requireNonEmpty("title", args.title);
+        requireIdempotencyKey("idempotencyKey", args.idempotencyKey);
+        rejectUnspecified("kind", [args.kind]);
+        try {
+            const res = await this.raw.recordPlatformAnnotation({
+                kind: args.kind,
+                title: args.title,
+                ...(args.startAt !== undefined ? { startAt: timestampFromDate(args.startAt) } : {}),
+                ...(args.endAt !== undefined ? { endAt: timestampFromDate(args.endAt) } : {}),
+                attributes: (args.attributes ?? []),
+                links: (args.links ?? []),
+                idempotencyKey: args.idempotencyKey,
+            });
+            return ok(res);
+        }
+        catch (e) {
+            const detail = findDetail(e, PlatformAnnotationRejectionV1Schema);
+            if (detail !== undefined) {
+                return err(toAnnotationRejection(detail));
+            }
+            throw e;
+        }
+    }
+    /**
+     * List annotations overlapping a window. `resync`, when present, is a typed
+     * directive that the caller's cursor cannot be honoured and the listing must
+     * be restarted — it arrives with an empty page, never as a transport error.
+     */
+    async listAnnotations(args) {
+        const windowStart = args.windowStart instanceof Date ? timestampFromDate(args.windowStart) : args.windowStart;
+        const windowEnd = args.windowEnd instanceof Date ? timestampFromDate(args.windowEnd) : args.windowEnd;
+        if (args.kinds !== undefined) {
+            rejectUnspecified("kinds", args.kinds);
+        }
+        const res = await this.raw.listPlatformAnnotations({
+            windowStart,
+            windowEnd,
+            kinds: (args.kinds ?? []),
+            page: {
+                ...(args.limit !== undefined ? { limit: args.limit } : {}),
+                ...(args.pageToken !== undefined ? { pageToken: args.pageToken } : {}),
+            },
+        });
+        return {
+            annotations: res.annotations,
+            nextPageToken: res.page?.nextPageToken,
+            hasMore: res.page?.hasMore ?? false,
+            resync: res.resync !== undefined ? toCursorResync(res.resync) : undefined,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@o11y-one/sdk` — hand-written client layer over the generated `@o11y-one/api-agentic`.
+ *
+ * The foundation:
+ *   - transport construction (client.ts)
+ *   - credential injection and its local validation (auth.ts)
+ *   - the failure taxonomy an SDK exists to render (errors.ts)
+ *
+ * The agentic-evaluation journey surface (evaluation.ts) binds the code-first
+ * loop's verbs — identity, machine credentials, run submission, the
+ * externally-executed lease loop, dataset drafts, annotations — as thin, typed,
+ * validated wrappers. Its refusals are TYPED VALUES (refusals.ts) returned in a
+ * `Result` (result.ts), not thrown-away errors; its inputs are guarded
+ * synchronously (validate.ts) before a wire call. The generated client stays
+ * reachable for any verb the surface has not lifted.
+ */
+export { O11yClient, createTransport, credentialInterceptor, type ClientOptions, } from "./client.js";
+export { assertLooksLikeMachineCredential, CREDENTIAL_HEADER, CREDENTIAL_MAX_LEN, MACHINE_CREDENTIAL_PREFIX, ORG_ID_HEADER, TENANT_ID_HEADER, type MachineCredential, } from "./auth.js";
+export { classify, MACHINE_SCOPES, type ClassifiedFailure, type FailureDisposition, type MachineScope, } from "./errors.js";
+export { AgenticEvaluationClient, OneTimeCredential, scopesToCanonical, type CallerIdentity, type LeaseOutcome, } from "./evaluation.js";
+export { ok, err, isOk, isErr, unwrap, type Result, type Ok, type Err, } from "./result.js";
+export { ValidationError, requireNonEmpty, requireIdempotencyKey, requireExactlyOne, rejectUnspecified, requireWithinBytes, byteLength, } from "./validate.js";
+export { findDetail, toLeaseRefusal, toCaseAck, toLaunchRejection, toCaptureRefusal, toDatasetVersionRejection, toAnnotationRejection, toCursorResync, type RecoveryAction, type LeaseRefusal, type LeaseRefusalReason, type CaseAck, type CaseAckKind, type SubmissionOutcome, type LaunchRejection, type LaunchRejectionReason, type CaptureRefusal, type CaptureRefusalReason, type DatasetVersionRejection, type DatasetVersionRejectionReason, type AnnotationRejection, type AnnotationRejectionReason, type CursorResync, type CursorResyncReason, } from "./refusals.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@o11y-one/sdk` — hand-written client layer over the generated `@o11y-one/api-agentic`.
+ *
+ * The foundation:
+ *   - transport construction (client.ts)
+ *   - credential injection and its local validation (auth.ts)
+ *   - the failure taxonomy an SDK exists to render (errors.ts)
+ *
+ * The agentic-evaluation journey surface (evaluation.ts) binds the code-first
+ * loop's verbs — identity, machine credentials, run submission, the
+ * externally-executed lease loop, dataset drafts, annotations — as thin, typed,
+ * validated wrappers. Its refusals are TYPED VALUES (refusals.ts) returned in a
+ * `Result` (result.ts), not thrown-away errors; its inputs are guarded
+ * synchronously (validate.ts) before a wire call. The generated client stays
+ * reachable for any verb the surface has not lifted.
+ */
+export { O11yClient, createTransport, credentialInterceptor, } from "./client.js";
+export { assertLooksLikeMachineCredential, CREDENTIAL_HEADER, CREDENTIAL_MAX_LEN, MACHINE_CREDENTIAL_PREFIX, ORG_ID_HEADER, TENANT_ID_HEADER, } from "./auth.js";
+export { classify, MACHINE_SCOPES, } from "./errors.js";
+// --- the journey surface ----------------------------------------------------
+export { AgenticEvaluationClient, OneTimeCredential, scopesToCanonical, } from "./evaluation.js";
+export { ok, err, isOk, isErr, unwrap, } from "./result.js";
+export { ValidationError, requireNonEmpty, requireIdempotencyKey, requireExactlyOne, rejectUnspecified, requireWithinBytes, byteLength, } from "./validate.js";
+export { findDetail, toLeaseRefusal, toCaseAck, toLaunchRejection, toCaptureRefusal, toDatasetVersionRejection, toAnnotationRejection, toCursorResync, } from "./refusals.js";

package/dist/refusals.d.ts

@@ -0,0 +1,116 @@
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+import { type ExternalLeaseRefusalV1, type EvaluationLaunchRejectionV1, type EvaluationCaptureRefusalV1, type EvaluationDatasetVersionRejectionV1, type PlatformAnnotationRejectionV1, type EvaluationCursorResyncV1, type ExternalCaseOutputAckV1 } from "@o11y-one/api-agentic/o11y_one/agentic/v1/evaluation_pb";
+/** The one remedial action the server named, as a wire enum member name. */
+export type RecoveryAction = "UNSPECIFIED" | "RETRY" | "RE_PREVIEW" | "EDIT_DEFINITION" | "WAIT" | "CONTACT_SUPPORT";
+export type LeaseRefusalReason = "UNSPECIFIED" | "RUN_NOT_EXECUTABLE" | "CANDIDATE_NOT_EXTERNALLY_EXECUTED" | "LEASE_NOT_HELD" | "LEASE_EXPIRED" | "RENEWAL_BUDGET_EXHAUSTED" | "BOUNDS_EXCEEDED" | "SCOPE_MISSING";
+export interface LeaseRefusal {
+    readonly type: "lease-refusal";
+    readonly reason: LeaseRefusalReason;
+    readonly message: string;
+    /** Set on `SCOPE_MISSING`: the canonical scope the credential lacks. */
+    readonly missingScope: string | undefined;
+    readonly recovery: RecoveryAction;
+    readonly raw: ExternalLeaseRefusalV1;
+}
+export declare function toLeaseRefusal(m: ExternalLeaseRefusalV1): LeaseRefusal;
+export type CaseAckKind = "UNSPECIFIED" | "ACCEPTED" | "ALREADY_SUBMITTED" | "REJECTED";
+export interface CaseAck {
+    readonly cohortKey: string;
+    readonly candidateKey: string;
+    readonly caseRevisionId: string;
+    readonly trial: number;
+    readonly kind: CaseAckKind;
+    /** The frozen execution state the server sees this coordinate in. */
+    readonly observedState: number;
+    readonly raw: ExternalCaseOutputAckV1;
+}
+export declare function toCaseAck(m: ExternalCaseOutputAckV1): CaseAck;
+/**
+ * The partial-batch outcome of a `submitCaseOutputs`. This is not an error even
+ * when `rejected` is non-empty: the accepted cases DID land, and the caller
+ * resubmits only the rejected coordinates. `refusal`, when present, is a
+ * WHOLE-request refusal (the fence was lost) and no per-case answer is
+ * meaningful — the two are never both set.
+ */
+export interface SubmissionOutcome {
+    readonly acceptedCount: number;
+    readonly alreadySubmittedCount: number;
+    readonly rejectedCount: number;
+    readonly acks: readonly CaseAck[];
+    readonly accepted: readonly CaseAck[];
+    readonly alreadySubmitted: readonly CaseAck[];
+    readonly rejected: readonly CaseAck[];
+    readonly remainingLeasedCaseCount: number;
+    /** Whole-request refusal; set only when the lease fence was lost. */
+    readonly refusal: LeaseRefusal | undefined;
+}
+export type LaunchRejectionReason = "UNSPECIFIED" | "PREVIEW_EXPIRED" | "PREVIEW_MALFORMED" | "DEFINITION_REVISION_MOVED" | "DEPENDENCY_VERSIONS_MOVED" | "CARDINALITY_MOVED" | "CAPABILITY_SET_MOVED" | "IDEMPOTENCY_KEY_REUSED";
+export interface LaunchRejection {
+    readonly type: "launch-rejection";
+    readonly reason: LaunchRejectionReason;
+    readonly expectedDigest: string;
+    readonly observedDigest: string;
+    /** Set on `IDEMPOTENCY_KEY_REUSED`: the run the key already named. */
+    readonly existingEvaluationRunId: string | undefined;
+    readonly recovery: RecoveryAction;
+    readonly detail: string;
+    readonly raw: EvaluationLaunchRejectionV1;
+}
+export declare function toLaunchRejection(m: EvaluationLaunchRejectionV1): LaunchRejection;
+export type CaptureRefusalReason = "UNSPECIFIED" | "SOURCE_NOT_FOUND" | "SOURCE_PLANE_NOT_SHIPPED" | "REQUIRED_FIELD_UNMAPPED" | "MAPPING_RESOLVED_NOTHING" | string;
+export interface CaptureRefusal {
+    readonly type: "capture-refusal";
+    readonly reason: CaptureRefusalReason;
+    readonly detail: string;
+    readonly missingTargetPaths: readonly string[];
+    readonly recovery: RecoveryAction;
+    /** Set on `IDEMPOTENCY_KEY_REUSED`: the case the key already captured. */
+    readonly existingProposedCaseId: string | undefined;
+    readonly raw: EvaluationCaptureRefusalV1;
+}
+export declare function toCaptureRefusal(m: EvaluationCaptureRefusalV1): CaptureRefusal;
+export type DatasetVersionRejectionReason = "UNSPECIFIED" | "COLLECTION_CAP_EXCEEDED" | "VERSION_CAP_ALL_PINNED" | "MALFORMED_JSONL_LINE" | "EMPTY_INGEST" | "INGEST_TOO_LARGE" | "DRAFT_NOT_FINALIZABLE" | "INGEST_BYTES_EXCEEDED" | "INGEST_CASE_COUNT_EXCEEDED" | "DRAFT_HAS_UNAPPROVED_CASES";
+export interface DatasetVersionRejection {
+    readonly type: "dataset-version-rejection";
+    readonly reason: DatasetVersionRejectionReason;
+    /** The server's stable `reason_code` string, carried alongside the kind. */
+    readonly reasonCode: string;
+    /** 1-based, set only on `MALFORMED_JSONL_LINE`. */
+    readonly lineNumber: number | undefined;
+    readonly observedCount: number;
+    readonly maxCount: number;
+    readonly detail: string;
+    readonly recovery: RecoveryAction;
+    readonly raw: EvaluationDatasetVersionRejectionV1;
+}
+export declare function toDatasetVersionRejection(m: EvaluationDatasetVersionRejectionV1): DatasetVersionRejection;
+export type AnnotationRejectionReason = "UNSPECIFIED" | "KIND_UNKNOWN" | "TITLE_TOO_LARGE" | "ATTRIBUTE_TOO_LARGE" | "TOO_MANY_ATTRIBUTES" | "TOO_MANY_LINKS" | "LINK_REF_TOO_LARGE" | "RANGE_INVERTED" | "IDEMPOTENCY_KEY_REUSED" | "WINDOW_INVALID";
+export interface AnnotationRejection {
+    readonly type: "annotation-rejection";
+    readonly reason: AnnotationRejectionReason;
+    /** The field the server refused, when it named one. */
+    readonly field: string | undefined;
+    /** The bound that was exceeded, when the reason is a size/count cap. */
+    readonly limitValue: bigint | undefined;
+    /** On `KIND_UNKNOWN`: the kinds this server DOES support, as wire names. */
+    readonly supportedKinds: readonly string[];
+    readonly raw: PlatformAnnotationRejectionV1;
+}
+export declare function toAnnotationRejection(m: PlatformAnnotationRejectionV1): AnnotationRejection;
+export type CursorResyncReason = "UNSPECIFIED" | "SNAPSHOT_SUPERSEDED" | "FILTER_CHANGED" | "CURSOR_MALFORMED" | "BACKLOG_EXCEEDED";
+export interface CursorResync {
+    readonly type: "cursor-resync";
+    readonly reason: CursorResyncReason;
+    readonly raw: EvaluationCursorResyncV1;
+}
+export declare function toCursorResync(m: EvaluationCursorResyncV1): CursorResync;
+/**
+ * Pull the first typed detail of a given schema off a thrown error.
+ *
+ * This is how a refusal that rides in `google.rpc.Status.details` (launch,
+ * capture, dataset-version, annotation) is recovered: connect-es already
+ * decodes `Status.details`, and `ConnectError.findDetails(schema)` hands back
+ * the typed messages. A non-Connect error, or a Connect error with no such
+ * detail, returns `undefined` and the caller rethrows.
+ */
+export declare function findDetail<Desc extends DescMessage>(error: unknown, schema: Desc): MessageShape<Desc> | undefined;