@opengeni/contracts 0.22.0 → 0.26.1

package/dist/retained-output.d.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+/** Hard server-side ceiling for one retained-output response body. */
+export declare const RETAINED_OUTPUT_MAX_PAGE_BYTES: number;
+/** Default first page when the client does not send a Range header. */
+export declare const RETAINED_OUTPUT_DEFAULT_PAGE_BYTES: number;
+/** Receipts are timeline references, never an extensible metadata bag. */
+export declare const RETAINED_OUTPUT_RECEIPT_MAX_BYTES: number;
+export declare const RetainedOutputKind: z.ZodEnum<{
+    assistant_completion: "assistant_completion";
+    event_media: "event_media";
+    file: "file";
+    internal_update: "internal_update";
+    tool_result: "tool_result";
+}>;
+export type RetainedOutputKind = z.infer<typeof RetainedOutputKind>;
+export declare const RetainedOutputUnavailableReason: z.ZodEnum<{
+    deleted: "deleted";
+    expired: "expired";
+    failed: "failed";
+    missing_storage: "missing_storage";
+    not_retained: "not_retained";
+    pending: "pending";
+    storage_write_failed: "storage_write_failed";
+    unsupported: "unsupported";
+}>;
+export type RetainedOutputUnavailableReason = z.infer<typeof RetainedOutputUnavailableReason>;
+export declare const RetainedArtifactReferenceSchema: z.ZodObject<{
+    available: z.ZodLiteral<true>;
+    artifactId: z.ZodString;
+    kind: z.ZodEnum<{
+        assistant_completion: "assistant_completion";
+        event_media: "event_media";
+        file: "file";
+        internal_update: "internal_update";
+        tool_result: "tool_result";
+    }>;
+    contentType: z.ZodString;
+    originalBytes: z.ZodNumber;
+    sha256: z.ZodString;
+    retainedAt: z.ZodString;
+    retention: z.ZodObject<{
+        policy: z.ZodLiteral<"workspace_file">;
+        expiresAt: z.ZodNull;
+    }, z.core.$strict>;
+    retrieval: z.ZodObject<{
+        method: z.ZodLiteral<"GET">;
+        path: z.ZodString;
+        acceptRanges: z.ZodLiteral<"bytes">;
+        maxRangeBytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * Canonical evidence fact carried by bounded audit/NATS/SSE/UI previews.
+ *
+ * The available variant is intentionally provider-neutral and closed: no bucket,
+ * object key, signed URL, arbitrary metadata, or producer-controlled labels can
+ * cross this boundary.
+ */
+export declare const RetainedOutputEvidenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    reason: z.ZodEnum<{
+        deleted: "deleted";
+        expired: "expired";
+        failed: "failed";
+        missing_storage: "missing_storage";
+        not_retained: "not_retained";
+        pending: "pending";
+        storage_write_failed: "storage_write_failed";
+        unsupported: "unsupported";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    available: z.ZodLiteral<true>;
+    artifactId: z.ZodString;
+    kind: z.ZodEnum<{
+        assistant_completion: "assistant_completion";
+        event_media: "event_media";
+        file: "file";
+        internal_update: "internal_update";
+        tool_result: "tool_result";
+    }>;
+    contentType: z.ZodString;
+    originalBytes: z.ZodNumber;
+    sha256: z.ZodString;
+    retainedAt: z.ZodString;
+    retention: z.ZodObject<{
+        policy: z.ZodLiteral<"workspace_file">;
+        expiresAt: z.ZodNull;
+    }, z.core.$strict>;
+    retrieval: z.ZodObject<{
+        method: z.ZodLiteral<"GET">;
+        path: z.ZodString;
+        acceptRanges: z.ZodLiteral<"bytes">;
+        maxRangeBytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>], "available">;
+export type RetainedOutputEvidence = z.infer<typeof RetainedOutputEvidenceSchema>;
+export type RetainedArtifactReference = z.infer<typeof RetainedArtifactReferenceSchema>;
+/** @deprecated use RetainedArtifactReference. */
+export type RetainedOutputAvailableEvidence = RetainedArtifactReference;
+export declare const RetainedArtifactUnavailableSchema: z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    artifactId: z.ZodString;
+    reason: z.ZodEnum<{
+        deleted: "deleted";
+        expired: "expired";
+        failed: "failed";
+        missing_storage: "missing_storage";
+        not_retained: "not_retained";
+        pending: "pending";
+        storage_write_failed: "storage_write_failed";
+        unsupported: "unsupported";
+    }>;
+}, z.core.$strict>;
+export type RetainedArtifactUnavailable = z.infer<typeof RetainedArtifactUnavailableSchema>;
+/** Authenticated metadata result for one opaque workspace file identity. */
+export declare const RetainedArtifactMetadataSchema: z.ZodUnion<readonly [z.ZodObject<{
+    available: z.ZodLiteral<true>;
+    artifactId: z.ZodString;
+    kind: z.ZodEnum<{
+        assistant_completion: "assistant_completion";
+        event_media: "event_media";
+        file: "file";
+        internal_update: "internal_update";
+        tool_result: "tool_result";
+    }>;
+    contentType: z.ZodString;
+    originalBytes: z.ZodNumber;
+    sha256: z.ZodString;
+    retainedAt: z.ZodString;
+    retention: z.ZodObject<{
+        policy: z.ZodLiteral<"workspace_file">;
+        expiresAt: z.ZodNull;
+    }, z.core.$strict>;
+    retrieval: z.ZodObject<{
+        method: z.ZodLiteral<"GET">;
+        path: z.ZodString;
+        acceptRanges: z.ZodLiteral<"bytes">;
+        maxRangeBytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    artifactId: z.ZodString;
+    reason: z.ZodEnum<{
+        deleted: "deleted";
+        expired: "expired";
+        failed: "failed";
+        missing_storage: "missing_storage";
+        not_retained: "not_retained";
+        pending: "pending";
+        storage_write_failed: "storage_write_failed";
+        unsupported: "unsupported";
+    }>;
+}, z.core.$strict>]>;
+export type RetainedArtifactMetadata = z.infer<typeof RetainedArtifactMetadataSchema>;
+export type RetainedArtifactFileInput = {
+    id: string;
+    workspaceId: string;
+    status: string;
+    contentType: string;
+    sizeBytes: number;
+    sha256: string | null;
+    updatedAt: string;
+};
+/**
+ * Convert a ready, integrity-addressed workspace file into the only available
+ * retained-output receipt shape. Invalid, pending, or checksum-less files fail
+ * closed instead of implying that full evidence is retrievable.
+ */
+export declare function retainedArtifactReferenceFromFile(file: RetainedArtifactFileInput, kind?: RetainedOutputKind): RetainedArtifactReference | null;
+/** Parse and clone a trusted server receipt; invalid/untrusted data fails closed. */
+export declare function validateRetainedOutputEvidence(value: unknown): RetainedOutputEvidence | null;
+export declare function retainedOutputUnavailable(reason?: RetainedOutputUnavailableReason): RetainedOutputEvidence;
+export type RetainedOutputResolvedRange = {
+    kind: "range";
+    start: number;
+    end: number;
+    length: number;
+    totalBytes: number;
+    status: 200 | 206;
+    contentRange: string | null;
+    acceptRanges: "bytes";
+};
+export type RetainedOutputRangeResolution = RetainedOutputResolvedRange | {
+    kind: "empty";
+    length: 0;
+    totalBytes: 0;
+    status: 200;
+    contentRange: null;
+    acceptRanges: "bytes";
+} | {
+    kind: "invalid";
+    reason: "malformed" | "multipart_not_supported" | "numeric_overflow" | "range_too_large";
+    maxPageBytes: number;
+} | {
+    kind: "unsatisfiable";
+    reason: "empty_artifact" | "start_out_of_bounds" | "end_before_start" | "zero_suffix";
+    totalBytes: number;
+    contentRange: string;
+};
+/**
+ * Resolve one RFC-style bytes range without ever licensing a response larger
+ * than `maxPageBytes`. Multipart ranges and oversized explicit/suffix requests
+ * fail closed. An omitted or open-ended range becomes one resumable bounded page.
+ */
+export declare function resolveRetainedOutputRange(rangeHeader: string | null | undefined, totalBytes: number, maxPageBytes?: number): RetainedOutputRangeResolution;

package/dist/sandbox-snapshots.d.ts

@@ -0,0 +1,41 @@
+export declare const WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION: 2;
+export type WorkspaceTreeFingerprint = {
+    algorithm: "sha256";
+    sha256: string;
+    entryCount: number;
+    fileCount: number;
+    totalFileBytes: number;
+};
+export type TarWorkspaceArchiveDescriptor = {
+    version: 1;
+    revision: string;
+    archiveSha256: string;
+    archiveBytes: number;
+    capturedAt: string;
+    workspace: WorkspaceTreeFingerprint;
+};
+export type NativeSnapshotProvider = "e2b" | "modal_snapshot_directory" | "modal_snapshot_filesystem" | "runloop" | "vercel";
+export type NativeSnapshotRef = {
+    provider: NativeSnapshotProvider;
+    snapshotId: string;
+    workspacePersistence?: string;
+};
+export type NativeSnapshotDescriptor = {
+    version: typeof WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION;
+    kind: "provider_snapshot";
+    revision: string;
+    archiveSha256: string;
+    archiveBytes: number;
+    capturedAt: string;
+    provider: NativeSnapshotProvider;
+    snapshotId: string;
+    workspacePersistence?: string;
+};
+export type WorkspaceArchiveDescriptor = TarWorkspaceArchiveDescriptor | NativeSnapshotDescriptor;
+export declare const NATIVE_SNAPSHOT_PREFIXES: ReadonlyArray<{
+    provider: NativeSnapshotProvider;
+    prefix: string;
+}>;
+export declare function parseWorkspaceArchiveDescriptor(value: unknown): WorkspaceArchiveDescriptor | null;
+export declare function decodeNativeSnapshotRef(bytes: Uint8Array): NativeSnapshotRef | null;
+export declare function backendForNativeSnapshotProvider(provider: NativeSnapshotProvider): string;

package/dist/secret-redaction.d.ts

@@ -0,0 +1,40 @@
+export type SecretForRedaction = {
+    name: string;
+    value: string;
+};
+/**
+ * Returns true only for fields whose value is itself credential material.
+ * Container fields such as `headers` and URL fields are intentionally not
+ * included: their nested/value sanitizers retain useful names, hosts, paths,
+ * and non-sensitive query parameters.
+ */
+export declare function isSensitiveFieldName(name: string): boolean;
+/**
+ * Return true only for header names whose values are credential material.
+ * Ordinary protocol metadata (`content-type`, `accept`, `user-agent`, and
+ * pagination/signature headers outside this allowlist) must remain intact.
+ */
+export declare function isCredentialHeaderName(name: string): boolean;
+/**
+ * Redact only exact known-secret provenance from a structured object key.
+ * Generic field/header heuristics intentionally do not run here: a key is
+ * metadata unless the caller has proved that its bytes are secret material.
+ */
+export declare function redactSensitiveKey(key: string, knownSecrets?: readonly SecretForRedaction[]): string;
+/**
+ * Redact known secret provenance and common credential-bearing text shapes.
+ * This is deliberately a conservative safety boundary, not a promise of
+ * general-purpose DLP. It never includes a matched value in a marker or error.
+ */
+export declare function redactSensitiveText(text: string, knownSecrets?: readonly SecretForRedaction[]): string;
+/** Deeply redact plain structured data while retaining its diagnostic shape. */
+export declare function redactSensitiveData<T>(value: T, knownSecrets?: readonly SecretForRedaction[]): T;
+/** Build the worker-friendly single-argument redactor used at turn boundaries. */
+export declare function createSecretRedactor(knownSecrets: readonly SecretForRedaction[]): (value: unknown) => unknown;
+/**
+ * Redact a serialized JSON checkpoint without requiring it to be valid JSON.
+ * Valid JSON retains structure; malformed/opaque text still receives text
+ * classification and exact-known-value replacement.
+ */
+export declare function redactSerializedJson(serialized: string, knownSecrets?: readonly SecretForRedaction[]): string;
+export declare function identityRedactor<T>(value: T): T;

package/dist/slack-bot-scopes.d.ts

@@ -0,0 +1,16 @@
+export declare const OPENGENI_SLACK_BOT_REQUIRED_SCOPES: readonly ["canvases:read", "channels:history", "channels:read", "chat:write", "files:read", "groups:history", "groups:read", "im:history", "im:read", "im:write", "mpim:history", "mpim:read", "users:read"];
+/**
+ * Optional bot grants that remain inside the shipped bot's read/identity
+ * boundary. Every other unrequired scope fails closed, including unknown future
+ * Slack scopes, so verification, core routing, and UI eligibility cannot drift.
+ */
+export declare const OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES: readonly ["team:read"];
+/** @deprecated Use evaluateOpenGeniSlackBotScopes; an allowlist is the policy. */
+export declare const OPENGENI_SLACK_BOT_FORBIDDEN_SCOPES: readonly ["channels:join", "chat:write.public"];
+export type OpenGeniSlackBotScopePolicy = {
+    accepted: boolean;
+    missingRequired: string[];
+    unsupported: string[];
+};
+export declare function areOpenGeniSlackBotScopesAccepted(grantedScopes: readonly string[]): boolean;
+export declare function evaluateOpenGeniSlackBotScopes(grantedScopes: readonly string[]): OpenGeniSlackBotScopePolicy;

package/dist/slack-bot-scopes.js

@@ -0,0 +1,15 @@
+import {
+  OPENGENI_SLACK_BOT_FORBIDDEN_SCOPES,
+  OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
+  OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES,
+  areOpenGeniSlackBotScopesAccepted,
+  evaluateOpenGeniSlackBotScopes
+} from "./chunk-3B3XEYMN.js";
+export {
+  OPENGENI_SLACK_BOT_FORBIDDEN_SCOPES,
+  OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
+  OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES,
+  areOpenGeniSlackBotScopesAccepted,
+  evaluateOpenGeniSlackBotScopes
+};
+//# sourceMappingURL=slack-bot-scopes.js.map

package/dist/slack-bot-scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}