@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/dist/secret-generator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The one password generator shared by agents (`secret_save` with
+ * `generate`), the ask card's server-side generate, and the web/mobile UI.
+ *
+ * Isomorphic and dependency-free: randomness comes from
+ * `crypto.getRandomValues` unless a test injects `random`. Output is ASCII
+ * only, and every character is drawn uniformly from the selected alphabet by
+ * rejection sampling, so no modulo bias is introduced. When
+ * `requireEachClass` is set, whole candidates lacking an enabled class are
+ * rejected and redrawn, which keeps the result uniform over all compliant
+ * passwords.
+ */
+import { z } from "zod";
+export declare const SECRET_GENERATOR_DEFAULT_SYMBOLS = "!#%+-.:=?@_";
+/** Characters that are easy to confuse when a person reads them. */
+export declare const SECRET_GENERATOR_AMBIGUOUS_CHARACTERS = "0O1lI|";
+export declare const GeneratePasswordSpec: z.ZodObject<{
+    length: z.ZodDefault<z.ZodNumber>;
+    lowercase: z.ZodDefault<z.ZodBoolean>;
+    uppercase: z.ZodDefault<z.ZodBoolean>;
+    digits: z.ZodDefault<z.ZodBoolean>;
+    symbols: z.ZodDefault<z.ZodBoolean>;
+    symbolSet: z.ZodDefault<z.ZodString>;
+    excludeAmbiguous: z.ZodDefault<z.ZodBoolean>;
+    requireEachClass: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type GeneratePasswordSpec = z.infer<typeof GeneratePasswordSpec>;
+export type GeneratePasswordSpecInput = z.input<typeof GeneratePasswordSpec>;
+export declare class PasswordGeneratorError extends Error {
+    constructor(message: string);
+}
+/** The enabled character classes after exclusions; empty classes are dropped. */
+export declare function passwordCharacterClasses(spec: GeneratePasswordSpec): string[];
+/** Generate a password. The spec input is parsed (defaults applied) first. */
+export declare function generatePassword(spec?: GeneratePasswordSpecInput, random?: (n: number) => Uint8Array): string;
+export type PasswordStrengthLabel = "weak" | "fair" | "strong" | "very_strong";
+/**
+ * Estimated entropy from length and the character pools the password uses.
+ * A display hint for the UI, not a security decision.
+ */
+export declare function passwordStrength(password: string): {
+    bits: number;
+    label: PasswordStrengthLabel;
+};

package/dist/secret-references.d.ts

@@ -0,0 +1,90 @@
+export type SecretReferenceKind = "secret" | "secretfile";
+export type SecretReferenceTarget = {
+    form: "id";
+    itemId: string;
+    field: string | null;
+} | {
+    form: "path";
+    segments: [string] | [string, string] | [string, string, string];
+};
+export interface SecretReference {
+    kind: SecretReferenceKind;
+    raw: string;
+    /** Offsets in the source text; `end` is exclusive. */
+    start: number;
+    end: number;
+    target: SecretReferenceTarget;
+    otp: boolean;
+    previous: boolean;
+}
+export type SecretTextToken = 
+/** Escapes already unescaped. */
+{
+    type: "text";
+    value: string;
+} | {
+    type: "reference";
+    reference: SecretReference;
+} | {
+    type: "invalid";
+    raw: string;
+    start: number;
+    end: number;
+    reason: string;
+};
+/** Fast-path needle; also matches `{{secretfile:`. */
+export declare const SECRET_REFERENCE_MARKER = "{{secret";
+export declare class SecretReferenceSyntaxError extends Error {
+    readonly reason: string;
+    constructor(reason: string, message?: string);
+}
+export declare function containsSecretReference(text: string): boolean;
+/**
+ * Split text into literal text, references and invalid candidates. Adjacent
+ * text is merged; an escaped reference (`\{{secret:…}}`) becomes literal
+ * text without the backslash. Never throws.
+ */
+export declare function tokenizeSecretText(text: string): SecretTextToken[];
+/** Valid references only, in text order. */
+export declare function findSecretReferences(text: string): SecretReference[];
+/** Invalid candidates only, in text order. */
+export declare function findInvalidSecretReferences(text: string): Array<Extract<SecretTextToken, {
+    type: "invalid";
+}>>;
+/** Parse exactly one reference (`{{…}}`). Throws SecretReferenceSyntaxError. */
+export declare function parseSecretReference(raw: string): SecretReference;
+export type FormatSecretReferenceInput = {
+    kind?: SecretReferenceKind;
+    vault?: string;
+    item: string;
+    field?: string;
+    otp?: boolean;
+    previous?: boolean;
+} | {
+    kind?: SecretReferenceKind;
+    itemId: string;
+    field?: string;
+    otp?: boolean;
+    previous?: boolean;
+};
+/** Build a reference. Throws SecretReferenceSyntaxError when a name cannot be referenced. */
+export declare function formatSecretReference(input: FormatSecretReferenceInput): string;
+/** NFC + trim + lowercase. For UI and dedupe only; SQL `vault_name_key` is authoritative. */
+export declare function secretNameKey(name: string): string;
+/** Canonical dedupe key within one call (same target and modifiers → same key). */
+export declare function referenceKey(ref: SecretReference): string;
+/** Remove escapes (`\{{secret:…}}` → `{{secret:…}}`); references stay as written. */
+export declare function unescapeSecretText(text: string): string;
+/** Every valid reference in every string value of a JSON-like structure. */
+export declare function collectReferencesDeep(value: unknown): SecretReference[];
+/** Every invalid candidate in every string value of a JSON-like structure. */
+export declare function collectInvalidReferencesDeep(value: unknown): Array<Extract<SecretTextToken, {
+    type: "invalid";
+}>>;
+/**
+ * Deep copy with each reference replaced by `replace(ref)` and escapes
+ * removed. Strings without the marker are copied unchanged; invalid
+ * candidates are kept verbatim (callers reject them before replacing).
+ * Object keys are not rewritten.
+ */
+export declare function replaceReferencesDeep<T>(value: T, replace: (ref: SecretReference) => string): T;

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>>;