@o11y-one/sdk 0.0.0

package/dist/errors.js

@@ -0,0 +1,83 @@
+/**
+ * The O11y One error taxonomy, as the SDK must render it.
+ *
+ * From lane 50A's note: `UNAUTHENTICATED` vs `PERMISSION_DENIED` is the whole
+ * reason this layer exists. "Your token is invalid" and "your token is fine but
+ * this capability is not shipped / not granted" are different problems with
+ * different fixes, and collapsing them into "auth error" is the failure mode
+ * this file prevents.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+const CANONICAL_SCOPES = [
+    "eval:read",
+    "run:execute",
+    "dataset:write",
+    "lease:submit",
+    "platform-annotation:write",
+];
+export const MACHINE_SCOPES = CANONICAL_SCOPES;
+/**
+ * Classify a thrown error into the taxonomy above.
+ *
+ * Non-Connect errors pass through as `unclassified` rather than being forced
+ * into a bucket — a DNS failure is not an auth failure and pretending otherwise
+ * sends people down the wrong path.
+ */
+export function classify(err) {
+    if (!(err instanceof ConnectError)) {
+        return {
+            disposition: "unclassified",
+            code: undefined,
+            message: err instanceof Error ? err.message : String(err),
+            missingScope: undefined,
+            retryable: false,
+        };
+    }
+    switch (err.code) {
+        case Code.Unauthenticated:
+            return {
+                disposition: "reauthenticate",
+                code: err.code,
+                message: err.rawMessage,
+                missingScope: undefined,
+                retryable: false,
+            };
+        case Code.PermissionDenied: {
+            // The server names the missing canonical scope in the message when the
+            // cause is a scope gap. When it does not, the cause is the other
+            // PERMISSION_DENIED case: a machine credential on a non-machine surface.
+            const named = MACHINE_SCOPES.find((s) => err.rawMessage.includes(s));
+            return {
+                disposition: "insufficient-scope",
+                code: err.code,
+                message: err.rawMessage,
+                missingScope: named,
+                retryable: false,
+            };
+        }
+        case Code.InvalidArgument:
+            return {
+                disposition: "version-skew",
+                code: err.code,
+                message: err.rawMessage,
+                missingScope: undefined,
+                retryable: false,
+            };
+        case Code.Unavailable:
+            return {
+                disposition: "retry-with-backoff",
+                code: err.code,
+                message: err.rawMessage,
+                missingScope: undefined,
+                retryable: true,
+            };
+        default:
+            return {
+                disposition: "unclassified",
+                code: err.code,
+                message: err.rawMessage,
+                missingScope: undefined,
+                retryable: false,
+            };
+    }
+}

package/dist/evaluation.d.ts

@@ -0,0 +1,253 @@
+/**
+ * The agentic-evaluation journey surface: thin, typed, validated wrappers over
+ * the generated `AgenticEvaluationService` client.
+ *
+ * Every method here is one of two things and nothing else:
+ *   - a request SHAPED and VALIDATED before it leaves (validate.ts), or
+ *   - a response whose refusal is DECODED to a typed value (refusals.ts) rather
+ *     than thrown away.
+ *
+ * No server logic is reimplemented. The backend does the work; this class binds
+ * to its verbs, guards their inputs, and names their outcomes. The generated
+ * client is reachable as `.raw` for any verb this surface has not lifted.
+ */
+import type { Client } from "@connectrpc/connect";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { AgenticEvaluationService, PlatformAnnotationKindV1, type CreateEvaluationRunResponse, type PreviewEvaluationRunResponse, type GetCallerPrincipalResponse, type MachinePrincipalV1, type MachinePrincipalWithCredentialsV1, type MachineCredentialV1, type ExternalCaseLeaseV1, type ExternalCaseOutputV1, type LeasedEvaluationCaseV1, type CreateEvaluationDatasetVersionResponse, type CaptureEvaluationCaseResponse, type PublishDatasetCaseDraftsResponse, type RecordPlatformAnnotationResponse, type PlatformAnnotationV1, type PlatformAnnotationAttributeV1, type PlatformAnnotationLinkV1, type EvaluationCaptureSpanSourceV1, type EvaluationCaptureCellSourceV1, type DatasetFieldMappingV1 } from "@o11y-one/api-agentic/o11y_one/agentic/v1/evaluation_pb";
+import type { O11yClient } from "./client.js";
+import type { MachineScope } from "./errors.js";
+import { type Result } from "./result.js";
+import { type LaunchRejection, type CaptureRefusal, type DatasetVersionRejection, type AnnotationRejection, type LeaseRefusal, type CursorResync, type SubmissionOutcome } from "./refusals.js";
+/** Canonical scope strings for a set of wire discriminants; UNSPECIFIED drops. */
+export declare function scopesToCanonical(values: readonly number[]): MachineScope[];
+/**
+ * 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 declare class OneTimeCredential {
+    #private;
+    /** The credential-id this token belongs to, safe to log. */
+    readonly credentialId: string;
+    constructor(plaintext: string, credentialId: string);
+    /** Hand over the plaintext. Store it in your secret manager; never log it. */
+    reveal(): string;
+    toString(): string;
+    toJSON(): string;
+}
+/** Who the credential authenticates as, and what it may do — before any run. */
+export interface CallerIdentity {
+    readonly tenantId: string;
+    readonly orgId: string;
+    /** Absent for a browser session; present for a machine credential. */
+    readonly machinePrincipalId: string | undefined;
+    /** The credential id that authorized this request; absent for a session. */
+    readonly credentialId: string | undefined;
+    /** The credential's scopes, as canonical strings. */
+    readonly scopes: readonly MachineScope[];
+    /** True when the credential carries `scope`. The pre-run gate `doctor` needs. */
+    readonly hasScope: (scope: MachineScope) => boolean;
+    readonly raw: GetCallerPrincipalResponse;
+}
+/** The outcome of a lease attempt that was not refused. */
+export interface LeaseOutcome {
+    /** The fenced hold, or absent when nothing was claimable. */
+    readonly lease: ExternalCaseLeaseV1 | undefined;
+    readonly cases: readonly LeasedEvaluationCaseV1[];
+    readonly remainingUnleasedCaseCount: number;
+    /**
+     * True when the lease is absent AND nothing remains: the honest "you are
+     * done" answer, distinct from "held by another runtime" (lease absent,
+     * remaining > 0).
+     */
+    readonly exhausted: boolean;
+}
+export declare class AgenticEvaluationClient {
+    readonly raw: Client<typeof AgenticEvaluationService>;
+    constructor(client: O11yClient);
+    /**
+     * 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.
+     */
+    whoami(): Promise<CallerIdentity>;
+    createMachinePrincipal(args: {
+        displayName: string;
+        description?: string;
+        scopes: readonly MachineScope[];
+    }): Promise<MachinePrincipalV1>;
+    listMachinePrincipals(args?: {
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<{
+        principals: MachinePrincipalWithCredentialsV1[];
+        nextPageToken: string | undefined;
+    }>;
+    /**
+     * Mint a credential. The plaintext comes back once, wrapped in a
+     * {@link OneTimeCredential} the caller must `reveal()` to read and can never
+     * accidentally log.
+     */
+    createMachineCredential(args: {
+        machinePrincipalId: string;
+        description?: string;
+        expiresAt?: Date;
+    }): Promise<{
+        credential: MachineCredentialV1;
+        token: OneTimeCredential;
+    }>;
+    revokeMachineCredential(args: {
+        credentialId: string;
+        revokeReason?: string;
+    }): Promise<MachineCredentialV1>;
+    revokeMachinePrincipal(args: {
+        machinePrincipalId: string;
+        revokeReason?: string;
+    }): Promise<{
+        principal: MachinePrincipalV1;
+        revokedCredentials: MachineCredentialV1[];
+    }>;
+    /**
+     * 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.
+     */
+    previewRun(args: {
+        definitionId: string;
+        revisionId?: string;
+    }): Promise<PreviewEvaluationRunResponse>;
+    /**
+     * 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.
+     */
+    launchRun(args: {
+        definitionId: string;
+        idempotencyKey: string;
+        previewToken: string;
+    }): Promise<Result<CreateEvaluationRunResponse, LaunchRejection>>;
+    /**
+     * 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`.
+     */
+    leaseCases(args: {
+        evaluationRunId: string;
+        candidateKey: string;
+        runtimeKey: string;
+        maxCases?: number;
+        leaseSeconds?: number;
+    }): Promise<Result<LeaseOutcome, LeaseRefusal>>;
+    /** Heartbeat a held lease. `err(LeaseRefusal)` when the fence was lost. */
+    renewLease(args: {
+        evaluationRunId: string;
+        leaseId: string;
+        leaseToken: string;
+        leaseSeconds?: number;
+    }): Promise<Result<ExternalCaseLeaseV1, LeaseRefusal>>;
+    /**
+     * 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`.
+     */
+    submitCaseOutputs(args: {
+        evaluationRunId: string;
+        leaseId: string;
+        leaseToken: string;
+        outputs: readonly ExternalCaseOutputV1[];
+        idempotencyKey: string;
+    }): Promise<SubmissionOutcome>;
+    /** Release a held lease early. `err(LeaseRefusal)` when the fence was lost. */
+    releaseLease(args: {
+        evaluationRunId: string;
+        leaseId: string;
+        leaseToken: string;
+    }): Promise<Result<number, LeaseRefusal>>;
+    /**
+     * 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.
+     */
+    createDatasetVersion(args: {
+        datasetCollectionId?: string;
+        collectionName?: string;
+        label?: string;
+        jsonl?: Uint8Array;
+        draftId?: string;
+        recordedOutputFieldPath?: string;
+        expectedDraftVersion?: bigint;
+        idempotencyKey: string;
+    }): Promise<Result<CreateEvaluationDatasetVersionResponse, DatasetVersionRejection>>;
+    /**
+     * 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`).
+     */
+    captureCase(args: {
+        datasetCollectionId: string;
+        draftId?: string;
+        span?: EvaluationCaptureSpanSourceV1;
+        cell?: EvaluationCaptureCellSourceV1;
+        fieldMappings?: readonly DatasetFieldMappingV1[];
+        recordedOutputFieldPath?: string;
+        baseDatasetVersionId?: string;
+        expectedContentDigest?: string;
+        idempotencyKey: string;
+    }): Promise<Result<CaptureEvaluationCaseResponse, CaptureRefusal>>;
+    /**
+     * Publish a reviewed changeset. A digest mismatch is a FAILED_PRECONDITION
+     * transport error (never a silent rebase) and is thrown for `classify()`.
+     */
+    publishDatasetDrafts(args: {
+        changesetId: string;
+        previewDigest: string;
+        label?: string;
+        idempotencyKey: string;
+    }): Promise<PublishDatasetCaseDraftsResponse>;
+    /**
+     * 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.
+     */
+    recordAnnotation(args: {
+        kind: PlatformAnnotationKindV1;
+        title: string;
+        startAt?: Date;
+        endAt?: Date;
+        attributes?: readonly PlatformAnnotationAttributeV1[];
+        links?: readonly PlatformAnnotationLinkV1[];
+        idempotencyKey: string;
+    }): Promise<Result<RecordPlatformAnnotationResponse, AnnotationRejection>>;
+    /**
+     * 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.
+     */
+    listAnnotations(args: {
+        windowStart: Date | Timestamp;
+        windowEnd: Date | Timestamp;
+        kinds?: readonly PlatformAnnotationKindV1[];
+        limit?: number;
+        pageToken?: string;
+    }): Promise<{
+        annotations: PlatformAnnotationV1[];
+        nextPageToken: string | undefined;
+        hasMore: boolean;
+        resync: CursorResync | undefined;
+    }>;
+}