@opengeni/contracts 3.1.0-canary.2 → 3.1.2

package/dist/secret-resolution.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Secret resolver contract (design §10B.1.3). Types live here; the hosted
+ * implementation is `createSecretResolver` in `@opengeni/core` and a static
+ * stub is `createStaticSecretResolver` in `@opengeni/vaults/testing`.
+ *
+ * Invariants: a call resolves all of its references or fails before
+ * dispatch (I2); plaintext only ever lives in `ResolvedSecretValue.material`
+ * and in delivery locals (I1); TOTP codes are computed at dispatch (I4).
+ */
+import type { RequestHumanInputToolInput } from "./index.js";
+import { type SecretReference } from "./secret-references.js";
+import { type SecretClock, type TotpParams } from "./secret-totp.js";
+import type { VaultSource } from "./vaults.js";
+export type SecretPrincipal = {
+    kind: "attempt";
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+} | {
+    kind: "site_viewer";
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    siteId: string;
+    siteVersion: string;
+} | {
+    kind: "human";
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    verifiedHuman: boolean;
+    viaApiKey: boolean;
+};
+export declare const SECRET_USE_SURFACES: readonly ["shell", "stdin", "file_write", "secretfile", "view_image", "run_on", "mcp", "codemode", "site", "browser", "desktop", "human_reveal"];
+export type SecretUseSurface = (typeof SECRET_USE_SURFACES)[number];
+export interface SecretUseContext {
+    surface: SecretUseSurface;
+    toolName: string;
+    operationId?: string;
+    sourceCallId?: string;
+}
+export type SecretMaterial = {
+    type: "text";
+    value: string;
+}
+/** File fields. */
+ | {
+    type: "bytes";
+    value: Uint8Array;
+}
+/** The code is computed at dispatch (I4). */
+ | {
+    type: "totp";
+    params: TotpParams;
+};
+export interface ResolvedSecretValue {
+    /** `referenceKey(reference)` */
+    key: string;
+    reference: SecretReference;
+    source: VaultSource;
+    vaultId: string;
+    vaultName: string;
+    itemId: string;
+    itemName: string;
+    fieldId: string | null;
+    fieldName: string;
+    version: number | null;
+    material: SecretMaterial;
+}
+export interface SecretResolver {
+    readonly principal: SecretPrincipal;
+    /** false when agent.capabilities.secrets is off: adapters must pass references through literally (Q-35). */
+    readonly enabled: boolean;
+    /** All-or-nothing (I2). Throws SecretReferenceError. Keys are referenceKey(ref). */
+    resolve(refs: readonly SecretReference[], use: SecretUseContext): Promise<Map<string, ResolvedSecretValue>>;
+}
+export declare const SECRET_REFERENCE_FAILURE_CODES: readonly ["invalid_reference", "not_found", "ambiguous", "denied", "no_primary_field", "provider_unavailable", "provider_rate_limited", "provider_auth_expired", "too_large", "binary_value", "unsupported_shell", "secretfile_not_allowed"];
+export type SecretReferenceFailureCode = (typeof SECRET_REFERENCE_FAILURE_CODES)[number];
+export interface SecretReferenceFailure {
+    raw: string;
+    code: SecretReferenceFailureCode;
+    message: string;
+    /** ambiguous: ready references to choose from (Q-49). */
+    candidates?: string[];
+}
+export declare const SECRET_REFERENCE_ERROR_CODE: "secret_reference_error";
+/** Thrown by `SecretResolver.resolve` and by delivery adapters before dispatch. */
+export declare class SecretReferenceError extends Error {
+    readonly code: "secret_reference_error";
+    readonly failures: SecretReferenceFailure[];
+    readonly askCard: RequestHumanInputToolInput | null;
+    constructor(failures: SecretReferenceFailure[], askCard?: RequestHumanInputToolInput | null);
+    /** JSON string for tool output: {error, failures, askCard, hint}. Never contains values. */
+    toModelOutput(): string;
+}
+export declare function isSecretReferenceError(error: unknown): error is SecretReferenceError;
+/** Materialize at dispatch: text/bytes as-is; TOTP via totpCodeAtDispatch (waits when < 3 s remain). */
+export declare function secretValueAtDispatch(v: ResolvedSecretValue, clock?: SecretClock): Promise<string | Uint8Array>;
+/**
+ * The ready-made ask card for `not_found` failures (§10B.1.3, D11): one
+ * secret question per missing item. Path references name the item in their
+ * last item segment (`Item`, `Item/field` read as Item/field, `Vault/Item/field`);
+ * ID references cannot be asked for by name and are skipped. Returns null
+ * when nothing can be asked. The model submits it unchanged.
+ */
+export declare function buildMissingSecretAskCard(failures: readonly SecretReferenceFailure[], ctx: {
+    hasActingHuman: boolean;
+}): RequestHumanInputToolInput | null;

package/dist/secret-totp.d.ts

@@ -0,0 +1,41 @@
+export interface TotpParams {
+    secretBase32: string;
+    algorithm: "SHA1" | "SHA256" | "SHA512";
+    digits: 6 | 7 | 8;
+    periodSeconds: number;
+}
+export type SecretClock = {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+export declare const systemSecretClock: SecretClock;
+/** Wait for the next window when fewer than this many ms remain (Q-33). */
+export declare const TOTP_MIN_REMAINING_MS = 3000;
+export declare class TotpInputError extends Error {
+    constructor(message: string);
+}
+/** Uppercase, strip spaces, dashes and padding. */
+export declare function normalizeBase32Secret(input: string): string;
+export declare function decodeBase32(input: string): Uint8Array;
+/**
+ * Accepts an `otpauth://totp/...` URI or a bare Base32 seed (spaces, dashes,
+ * padding and lowercase tolerated). Throws `TotpInputError`.
+ */
+export declare function parseTotpInput(input: string): TotpParams;
+/** True when `input` parses as a TOTP seed or otpauth URI. */
+export declare function isValidTotpInput(input: string): boolean;
+/** Synchronous form of `totpCode` for UI rendering loops. */
+export declare function totpCodeSync(params: TotpParams, atMs: number): string;
+/** The code valid at `atMs` (Unix milliseconds). */
+export declare function totpCode(params: TotpParams, atMs: number): Promise<string>;
+/** Milliseconds left in the window containing `atMs`. */
+export declare function totpRemainingMs(params: TotpParams, atMs: number): number;
+/**
+ * The code to type or send right now. When fewer than 3 s remain in the
+ * current window, waits for the next window so the code is not stale on
+ * arrival (Q-33).
+ */
+export declare function totpCodeAtDispatch(params: TotpParams, clock?: SecretClock): Promise<{
+    code: string;
+    expiresAtMs: number;
+}>;

package/dist/session-final-reply.d.ts

@@ -0,0 +1,6 @@
+/** A response-quality notice, not a failed turn or a completed deliverable. */
+export declare const EMPTY_FINAL_REPLY_NOTICE = "The model returned no final reply after a reply reminder. Completed work is preserved; the goal and later updates are unaffected.";
+export type EmptyFinalReplyCompletion = {
+    emptyFinalReply: true;
+};
+export declare function turnCompletedWithEmptyFinalReply(payload: unknown): boolean;

package/dist/session-final-reply.js

@@ -0,0 +1,9 @@
+import {
+  EMPTY_FINAL_REPLY_NOTICE,
+  turnCompletedWithEmptyFinalReply
+} from "./chunk-KHHZTBP7.js";
+export {
+  EMPTY_FINAL_REPLY_NOTICE,
+  turnCompletedWithEmptyFinalReply
+};
+//# sourceMappingURL=session-final-reply.js.map

package/dist/session-final-reply.js.map

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

package/dist/session-goal-reports.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const SessionGoalReportRequirement: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strict>;
+export type SessionGoalReportRequirement = z.infer<typeof SessionGoalReportRequirement>;
+export declare const SessionGoalReportRequirements: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strict>>;
+export declare const SessionGoalReportDelivery: z.ZodObject<{
+    requirementId: z.ZodString;
+    artifactId: z.ZodString;
+    inspectionReceiptId: z.ZodString;
+}, z.core.$strict>;
+export type SessionGoalReportDelivery = z.infer<typeof SessionGoalReportDelivery>;
+export declare const SessionGoalReportDeliveries: z.ZodArray<z.ZodObject<{
+    requirementId: z.ZodString;
+    artifactId: z.ZodString;
+    inspectionReceiptId: z.ZodString;
+}, z.core.$strict>>;