@opengeni/core 3.0.1 → 3.1.2

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

@@ -1,5 +1,6 @@
-import { type AccessGrant, type ConnectionMetadata, type OpenGeniSlackBotConnectionMetadata as OpenGeniSlackBotMetadata, type Session } from "@opengeni/contracts";
+import { type AccessGrant, type ConnectionMetadata, type FirstPartyMcpToolName, type OpenGeniSlackBotConnectionMetadata as OpenGeniSlackBotMetadata, type ScheduledTask, type ScheduledTaskAgentConfig, type Session } from "@opengeni/contracts";
 import { type ConnectionMetadataWithVerification, type Database } from "@opengeni/db";
+import { type AccessGrantAuthorization } from "../access/index.js";
 export declare function openGeniSlackBotMetadata(metadata: Record<string, unknown>): OpenGeniSlackBotMetadata | null;
 export declare function isOpenGeniSlackBotConnection(connection: ConnectionMetadata & Partial<Pick<ConnectionMetadataWithVerification, "verifiedInstallAt" | "verifiedInstallVersion">>): boolean;
 export declare function hasReservedOpenGeniSlackBotMetadata(metadata: Record<string, unknown> | null | undefined): boolean;
@@ -17,3 +18,47 @@ export declare function scheduledSlackBotConnectionId(metadata: Record<string, u
  * an authorization mechanism for a workspace-shared bot credential.
  */
 export declare function isTrustedScheduledSlackBotSession(session: Pick<Session, "createdBy" | "createdByContext" | "metadata">): boolean;
+/**
+ * Proves, with the bot's own token, that it may post in the chosen channel:
+ * the bot is a member and the channel is active and not shared with another
+ * organization. Supplied only by the HTTP routes a person uses to edit tasks.
+ */
+export type ScheduledTaskSlackChannelVerifier = (input: {
+    connectionId: string;
+    channelId: string;
+}) => Promise<void>;
+/**
+ * Whether this request is a signed-in person acting for themselves: never an
+ * agent attempt, a service, an API key, or a request carrying service
+ * provenance. The same rule gates Agent learning settings.
+ */
+export declare function isAuthenticatedPersonAuthorization(authorization: AccessGrantAuthorization | undefined): boolean;
+/**
+ * A scheduled task may post as the Opengeni workspace bot only to the one
+ * Slack channel a person chose on the task. Choosing or changing that channel
+ * therefore needs a signed-in person with `connections:write`, and the bot's
+ * membership is verified at that moment. Keeping or clearing the existing
+ * channel needs neither, so an agent editing other task fields cannot redirect
+ * posts but also does not have to re-prove the person's choice. Clearing is the
+ * safe direction and is never refused, even for a task that continues one chat.
+ */
+export declare function validateScheduledTaskSlackChannel(input: {
+    grant: AccessGrant;
+    authorization?: AccessGrantAuthorization | undefined;
+    previous: Pick<ScheduledTaskAgentConfig, "slackBotConnectionId" | "slackBotChannelId"> | null;
+    next: Pick<ScheduledTaskAgentConfig, "slackBotConnectionId" | "slackBotChannelId">;
+    runMode: ScheduledTask["runMode"];
+    /**
+     * Null unless the task already created the reusable chat its runs continue.
+     * Otherwise reports whether that chat was created with the posting tools,
+     * which are fixed at creation.
+     */
+    reusableSessionCanPost: (() => Promise<boolean>) | null;
+    verifySlackChannel?: ScheduledTaskSlackChannelVerifier | undefined;
+}): Promise<void>;
+/**
+ * Add the bot posting tools to a generated scheduled run when, and only when,
+ * a person chose the task's Slack channel. The deployment ceiling still
+ * applies: an operator who disallowed these tools keeps them off.
+ */
+export declare function withScheduledSlackBotPostingTools(tools: readonly FirstPartyMcpToolName[], agentConfig: Pick<ScheduledTaskAgentConfig, "slackBotConnectionId" | "slackBotChannelId">, allowedTools: readonly FirstPartyMcpToolName[]): FirstPartyMcpToolName[];

package/dist/domain/slack-publication-secret-safety.d.ts

@@ -3,6 +3,6 @@ export declare const SLACK_PUBLICATION_CREDENTIAL_OMISSION = "[credential omitte
  * Deterministic, sink-local protection for text that is about to be persisted
  * as a Slack publication projection or rendered to Slack. It intentionally
  * does not scan or mutate canonical Memory, durable-learning receipts, model
- * context, history, events, or any other internal OpenGeni content path.
+ * context, history, events, or any other internal Opengeni content path.
  */
 export declare function sanitizeSlackPublicationText(value: string): string;

package/dist/domain/vaults/index.d.ts

@@ -0,0 +1,7 @@
+/** Vaults and secret references: the only import point for the vault domain. */
+export { buildMissingSecretAskCard } from "@opengeni/contracts";
+export { isVaultError, VaultError, vaultErrorFromDatabase } from "@opengeni/db";
+export { toVaultItem, toVaultItemSummary, toVaultSummary, vaultCanManage, vaultCanWrite, vaultItemReferences, type VaultCallerAuthority, } from "./mapping.js";
+export { chooseSecretCandidate, createSecretResolver, type SecretResolverOptions, } from "./secret-resolver.js";
+export type { VaultRequestActor, VaultServiceDeps } from "./types.js";
+export { createVaultService, vaultActorIsApiKey, type VaultService } from "./vault-service.js";

package/dist/domain/vaults/mapping.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Vault rows (encrypted, as the 0739 routines return them) to the public
+ * contract shapes. Only text-kind field values are decrypted for display;
+ * every other kind stays server-side until an audited reveal or a resolve.
+ */
+import { type VaultItem, type VaultItemReferences, type VaultItemSummary, type VaultSummary } from "@opengeni/contracts";
+import { type VaultItemRow, type VaultRow } from "@opengeni/db";
+/** What the caller may do beyond reading; decided by the route's grant. */
+export type VaultCallerAuthority = {
+    /** `secrets:write` */
+    write: boolean;
+    /** `account:admin` on the organization */
+    accountAdmin: boolean;
+};
+export declare function vaultCanWrite(row: VaultRow, authority: VaultCallerAuthority): boolean;
+export declare function vaultCanManage(row: VaultRow, authority: VaultCallerAuthority): boolean;
+export declare function toVaultSummary(row: VaultRow, authority: VaultCallerAuthority): VaultSummary;
+/**
+ * Ready references for an item. Every reference names the vault and the field
+ * (`{{secret:Vault/Item/field}}`), so it cannot become ambiguous when another
+ * reachable vault gains an item with the same name.
+ */
+export declare function vaultItemReferences(item: Pick<VaultItemRow, "id" | "name" | "vaultName" | "fields" | "primaryFieldId">): VaultItemReferences;
+export declare function toVaultItemSummary(row: VaultItemRow, key: Uint8Array | null): VaultItemSummary;
+export declare function toVaultItem(row: VaultItemRow, key: Uint8Array | null): VaultItem;

package/dist/domain/vaults/provider-registry.d.ts

@@ -0,0 +1,72 @@
+import type { Settings } from "@opengeni/config";
+import type { ConnectionMetadata, VaultErrorCode } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+import { type VaultProvider, type VaultProviderErrorCode, type VaultProviderRegistry } from "@opengeni/vaults";
+/**
+ * Provider error codes as vault API error codes (§10B.1.1). `provider_not_found`
+ * is the vault (or, for reads, the field); `provider_permission_denied` is
+ * `vault_read_only` for writes and `vault_permission_denied` otherwise.
+ */
+export declare function vaultErrorCodeForProvider(code: VaultProviderErrorCode, operation: "read" | "write" | "vault"): VaultErrorCode;
+/**
+ * 1Password service-account connections (design §10.9). The token lives in
+ * the existing encrypted connection-credential store as `{ token }` (no
+ * `headers`, so the egress broker can never inject it); metadata carries only
+ * `{ credentialRole, planTier, ownership, accountName, label, verifiedAt }`.
+ */
+export declare const ONEPASSWORD_PROVIDER_DOMAIN = "1password.com";
+export declare const ONEPASSWORD_CREDENTIAL_ROLE = "onepassword_service_account";
+export type OnePasswordPlanTier = "family" | "teams" | "business";
+export type OnePasswordConnectionOwnership = "user" | "workspace" | "organization";
+export type OnePasswordConnectionMetadata = {
+    credentialRole: typeof ONEPASSWORD_CREDENTIAL_ROLE;
+    planTier: OnePasswordPlanTier;
+    ownership: OnePasswordConnectionOwnership;
+    /** Sign-in host from the token, for example "my.1password.com". */
+    accountName: string | null;
+    label: string | null;
+    verifiedAt: string;
+};
+export declare function onePasswordConnectionMetadata(metadata: Record<string, unknown> | null | undefined): OnePasswordConnectionMetadata | null;
+export declare function isOnePasswordConnection(connection: ConnectionMetadata): boolean;
+/**
+ * Builds a provider for one stored token. Supplied by apps/api and apps/worker
+ * as `(input) => import("@opengeni/vaults-onepassword").then(...)`, so core
+ * never loads the 1Password SDK (OP-5).
+ */
+export type OnePasswordVaultProviderFactory = (input: {
+    token: string;
+    planTier: OnePasswordPlanTier;
+    allowFakeTokens: boolean;
+}) => Promise<VaultProvider>;
+export declare function onePasswordCredentialBundle(token: string): Record<string, unknown>;
+/**
+ * Decrypts the token of one 1Password connection the caller can use from
+ * `workspaceId`: one in this workspace (shared, or personal to `subjectId`),
+ * or one added in another workspace that still serves vaults reached here
+ * (the caller's own personal connection, or a shared connection behind an
+ * organization vault). The token goes only to the provider factory; it is
+ * never logged or returned to a client.
+ */
+export declare function loadOnePasswordConnectionToken(db: Database, settings: Settings, input: {
+    workspaceId: string;
+    connectionId: string;
+    subjectId: string | null;
+}): Promise<{
+    token: string;
+    metadata: OnePasswordConnectionMetadata;
+}>;
+/**
+ * The provider registry for one workspace request or attempt:
+ * - `onepassword` vaults load their connection token and the SDK lazily;
+ * - `host` vaults use the embedder's `connectionCredentials.vaultProvider`.
+ */
+export declare function createWorkspaceVaultProviderRegistry(input: {
+    db: Database;
+    settings: Settings;
+    workspaceId: string;
+    /** The acting subject; personal 1Password connections resolve only for their owner. */
+    subjectId: string | null;
+    hostVaultProvider?: VaultProvider | null;
+    onePasswordVaultProvider?: OnePasswordVaultProviderFactory | null;
+}): VaultProviderRegistry;

package/dist/domain/vaults/provider-sync.d.ts

@@ -0,0 +1,176 @@
+import { type VaultFieldKind, type VaultItemType, type VaultSyncStatus } from "@opengeni/contracts";
+import { type Database, type VaultDbContext } from "@opengeni/db";
+import { type ProviderItemMeta, type VaultProvider, type VaultProviderContext, type VaultProviderErrorCode, type VaultProviderRegistry } from "@opengeni/vaults";
+/**
+ * Provider vault metadata mirror (design §10.9, OP-1/OP-4). A linked
+ * 1Password or host vault keeps a metadata-only mirror (item names, types,
+ * websites, field names and kinds); values are always read live. A sync costs
+ * one `listVaults` call and skips `listItems` entirely when the provider's
+ * `contentVersion` is unchanged, so FAMILY-plan quotas are not burnt on
+ * no-op refreshes.
+ *
+ * The engine is storage-agnostic: the vault service binds `ProviderMirrorStore`
+ * to its tables (`vault_items`, `vault_item_fields`, `vaults.sync_status`,
+ * `vaults.rate_limited_until`).
+ */
+export interface ProviderMirrorField {
+    externalFieldId: string;
+    name: string;
+    kind: VaultFieldKind;
+    position: number;
+}
+export interface ProviderMirrorItem {
+    externalItemId: string;
+    /** Valid, vault-unique (case-insensitive) secret name. */
+    name: string;
+    /** The provider's own name, kept when it had to be sanitized or de-duplicated. */
+    providerName: string;
+    type: VaultItemType;
+    websites: string[];
+    fields: ProviderMirrorField[];
+    primaryExternalFieldId: string | null;
+    hasTotp: boolean;
+    version: string | null;
+    updatedAt: string | null;
+}
+export interface ProviderMirrorPlan {
+    contentVersion: string | null;
+    items: ProviderMirrorItem[];
+    /** Items beyond `VAULT_LIMITS.itemsPerVault` that were not mirrored. */
+    truncated: number;
+}
+export interface ProviderSyncStatusUpdate {
+    syncStatus: VaultSyncStatus;
+    syncErrorCode: VaultProviderErrorCode | null;
+    syncErrorMessage: string | null;
+    rateLimitedUntil: Date | null;
+    /** Set only when the provider was reached and the mirror is current. */
+    lastSyncedAt: Date | null;
+}
+export interface ProviderMirrorStore {
+    /** Replace the mirror for this vault in one transaction (upsert by external id, drop missing). */
+    replaceMirror(plan: ProviderMirrorPlan): Promise<void>;
+    setSyncStatus(update: ProviderSyncStatusUpdate): Promise<void>;
+}
+export interface ProviderVaultSyncTarget {
+    externalVaultId: string;
+    /** `contentVersion` recorded by the last successful mirror, if any. */
+    mirroredContentVersion: string | null;
+    rateLimitedUntil: Date | null;
+}
+export type ProviderVaultSyncResult = {
+    status: "synced";
+    contentVersion: string | null;
+    itemCount: number;
+    truncated: number;
+} | {
+    status: "unchanged";
+    contentVersion: string | null;
+} | {
+    status: "skipped_rate_limited";
+    rateLimitedUntil: Date;
+} | {
+    status: "failed";
+    syncStatus: VaultSyncStatus;
+    code: VaultProviderErrorCode;
+    rateLimitedUntil: Date | null;
+};
+/** When the provider gives no retry hint, back off this long after a 429. */
+export declare const PROVIDER_RATE_LIMIT_DEFAULT_BACKOFF_MS: number;
+/** Map a provider item name onto a valid secret name (Q-10). */
+export declare function providerSecretName(raw: string, fallback?: string): string;
+/** Appends " (2)", " (3)" … until the name is unique case-insensitively. */
+export declare function uniqueProviderName(name: string, taken: Set<string>): string;
+/**
+ * The field a bare `vault/item` reference resolves to: the item type's default
+ * (§10B.2), then password → value → credential → note by name, then the first
+ * concealed field. TOTP fields are never primary (they have `/otp`).
+ */
+export declare function providerPrimaryFieldId(item: Pick<ProviderItemMeta, "type" | "fields">): string | null;
+/**
+ * Deterministic mirror projection. Items are ordered by provider name then
+ * external id before de-duplication, so the same provider state always yields
+ * the same Opengeni names; field names are de-duplicated within each item.
+ */
+export declare function planProviderMirror(items: readonly ProviderItemMeta[], contentVersion: string | null): ProviderMirrorPlan;
+/** Sync status for a provider failure; rate limits persist `rateLimitedUntil`. */
+export declare function providerSyncFailure(error: unknown, now: Date): ProviderSyncStatusUpdate & {
+    syncErrorCode: VaultProviderErrorCode;
+};
+/**
+ * Refresh one linked vault's mirror. While `rateLimitedUntil` is in the future
+ * the provider is not called at all unless `force` is set.
+ */
+export declare function syncProviderVault(input: {
+    provider: VaultProvider;
+    ctx: VaultProviderContext;
+    target: ProviderVaultSyncTarget;
+    store: ProviderMirrorStore;
+    now?: () => Date;
+    /** Re-list items even when `contentVersion` is unchanged. */
+    force?: boolean;
+}): Promise<ProviderVaultSyncResult>;
+/** Binds the mirror store to the 0739 routines for one connected vault. */
+export declare function databaseProviderMirrorStore(db: Database, context: VaultDbContext, vaultId: string): ProviderMirrorStore;
+/**
+ * Sync one linked vault the caller reaches: load its provider refs and mirror
+ * version, resolve its provider, refresh the mirror and record sync status.
+ */
+export declare function syncLinkedProviderVault(input: {
+    db: Database;
+    context: VaultDbContext;
+    vaultId: string;
+    providers: VaultProviderRegistry;
+    budget?: VaultProviderContext["budget"];
+    force?: boolean;
+    now?: () => Date;
+}): Promise<ProviderVaultSyncResult>;
+/** How stale a linked vault's mirror may be before a search refreshes it. */
+export declare const LINKED_VAULT_SEARCH_MAX_AGE_MS: number;
+/** How stale it may be before a reference that found nothing refreshes it. */
+export declare const LINKED_VAULT_MISS_MAX_AGE_MS: number;
+/** How long a search or resolution waits for refreshes before answering. */
+export declare const LINKED_VAULT_REFRESH_WAIT_MS = 8000;
+/**
+ * How long a person opening a linked vault waits for its stale mirror to
+ * refresh before the page shows what is mirrored; a slower refresh finishes in
+ * the background and the next load shows it.
+ */
+export declare const LINKED_VAULT_OPEN_WAIT_MS = 3000;
+/** The vault fields a freshness check needs (a `VaultRow` has them all). */
+export type LinkedVaultFreshness = {
+    id: string;
+    source: string;
+    syncStatus: VaultSyncStatus;
+    lastSyncedAt: string | null;
+    rateLimitedUntil: string | null;
+    updatedAt: string;
+};
+/**
+ * Whether a linked vault's mirror is older than `maxAgeMs`. A vault whose last
+ * sync failed counts from that failure (it is recorded as `updatedAt`), so a
+ * broken connection is retried once per `maxAgeMs`, not on every call. A vault
+ * under a provider rate limit is never stale until the limit lifts.
+ */
+export declare function linkedVaultNeedsRefresh(vault: LinkedVaultFreshness, maxAgeMs: number, now: Date): boolean;
+/**
+ * Bring stale linked vault mirrors up to date, so items added in the provider
+ * (for example straight in 1Password) are found without anyone pressing Sync.
+ *
+ * Each refresh is the ordinary non-forced sync: one `listVaults` call, and an
+ * item listing only when the provider says the vault changed. Refreshes of the
+ * same vault share one call per process. The caller waits at most `waitMs`;
+ * slower refreshes finish in the background and record their own status.
+ * Never throws: failures are recorded as the vault's sync status.
+ *
+ * Returns the ids of the vaults whose mirror changed before the wait ended.
+ */
+export declare function refreshStaleLinkedVaults(input: {
+    db: Database;
+    context: VaultDbContext;
+    vaults: readonly LinkedVaultFreshness[];
+    providers: VaultProviderRegistry;
+    maxAgeMs: number;
+    waitMs?: number;
+    now?: () => Date;
+}): Promise<string[]>;

package/dist/domain/vaults/provider-writes.d.ts

@@ -0,0 +1,57 @@
+import { type VaultFieldInput, type VaultFieldKind, type VaultItemType } from "@opengeni/contracts";
+import { type Database, type VaultDbContext, type VaultFieldRow, type VaultRow } from "@opengeni/db";
+import { type ProviderCallBudget, type VaultProviderRegistry } from "@opengeni/vaults";
+/**
+ * Edits of items in a read-write connected vault (OP-3): the change is written
+ * to the provider (1Password `items.get` → patch → `items.put`, with the
+ * mirrored version as the expected version), then the metadata mirror is
+ * refreshed. Values never touch Opengeni storage.
+ */
+/** One field change; the REST `VaultFieldInput` and the agent `secret_save` field both fit. */
+export interface ProviderFieldChange {
+    fieldId?: string | undefined;
+    name: string;
+    kind?: VaultFieldKind | undefined;
+    value?: string | undefined;
+    generate?: VaultFieldInput["generate"] | undefined;
+    fromReference?: string | undefined;
+    fileBase64?: string | undefined;
+    restoreVersion?: number | undefined;
+    remove?: true | undefined;
+}
+export interface ProviderItemChange {
+    name?: string | undefined;
+    type?: VaultItemType | undefined;
+    websites?: string[] | undefined;
+    fields?: readonly ProviderFieldChange[] | undefined;
+}
+export interface ProviderWriteDeps {
+    db: Database;
+    context: VaultDbContext;
+    providers: VaultProviderRegistry;
+    /** Resolves `fromReference` field inputs (audited as a use by the caller). */
+    resolveReference: (raw: string) => Promise<string>;
+    budget?: ProviderCallBudget;
+}
+/** A connected vault the caller may change items in. */
+export declare function assertProviderVaultWritable(vault: VaultRow): void;
+/** Create (existing = null) or update an item in a connected read-write vault; returns its item id. */
+export declare function writeProviderVaultItem(deps: ProviderWriteDeps, input: {
+    vault: VaultRow;
+    existing: {
+        itemId: string;
+        name: string;
+        type: VaultItemType;
+        websites: string[];
+        fields: VaultFieldRow[];
+        expectedGeneration?: number | undefined;
+    } | null;
+    change: ProviderItemChange;
+    /** Receives the names of fields whose values were generated. */
+    generated?: string[];
+}): Promise<string>;
+/** Archive an item in a connected read-write vault (the provider keeps it recoverable). */
+export declare function archiveProviderVaultItem(deps: ProviderWriteDeps, input: {
+    vault: VaultRow;
+    itemId: string;
+}): Promise<void>;

package/dist/domain/vaults/secret-resolver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The hosted secret resolver (§10B.2). One database roundtrip returns the
+ * principal's facts and every candidate for every reference; candidates are
+ * chosen here (archived dropped, lowest tier, names over aliases, otherwise
+ * ambiguous), provider values are fetched, hosted values decrypted, and the
+ * batch is recorded. A call resolves all of its references or none (I2).
+ */
+import { type SecretPrincipal, type SecretReference, type SecretReferenceFailure, type SecretResolver } from "@opengeni/contracts";
+import { type SecretReferenceCandidate, type SecretResolutionMeta } from "@opengeni/db";
+import { type ProviderCallBudget, type VaultProviderRegistry } from "@opengeni/vaults";
+import type { VaultServiceDeps } from "./types.js";
+export type SecretResolverOptions = {
+    /** `agent.capabilities.secrets`; when false the resolver refuses every reference. */
+    capabilityEnabled: boolean;
+    /** Provider calls allowed for this attempt (Q-18); a fresh 50-call budget by default. */
+    attemptBudget?: ProviderCallBudget;
+    /**
+     * Connected vaults for callers that only learn the acting human from the
+     * lookup itself (browser and computer routes, `run_on`, the tool gateway):
+     * 1Password connection tokens load for that subject. `deps.providers` wins.
+     */
+    providersForSubject?: (subjectId: string | null) => VaultProviderRegistry;
+};
+/**
+ * Choose one candidate per reference (§10B.2): drop archived items, keep the
+ * lowest tier, prefer names over aliases; more than one remaining target is
+ * ambiguous and returns ready references to choose from.
+ */
+export declare function chooseSecretCandidate(reference: SecretReference, candidates: readonly SecretReferenceCandidate[], meta: SecretResolutionMeta): {
+    candidate: SecretReferenceCandidate;
+} | {
+    failure: SecretReferenceFailure;
+};
+export declare function createSecretResolver(deps: VaultServiceDeps, principal: SecretPrincipal, opts: SecretResolverOptions): SecretResolver;

package/dist/domain/vaults/types.d.ts

@@ -0,0 +1,24 @@
+import type { AccessGrant, SecretClock } from "@opengeni/contracts";
+import type { Database } from "@opengeni/db";
+import type { VaultProviderRegistry } from "@opengeni/vaults";
+export interface VaultServiceDeps {
+    db: Database;
+    /**
+     * The variable-set envelope key (`OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY`);
+     * null when unconfigured, which fails value reads and writes with
+     * `encryption_key_missing`.
+     */
+    encryptionKey: Uint8Array | null;
+    /** Provider vaults (1Password, host); none configured by default. */
+    providers?: VaultProviderRegistry;
+    clock?: SecretClock;
+}
+/**
+ * A person or API key calling the vault API. Routes check the permission each
+ * operation needs; the actor carries what the service needs on top of that.
+ */
+export interface VaultRequestActor {
+    grant: AccessGrant;
+    /** The caller holds `account:admin` on the organization (organization vaults). */
+    accountAdmin: boolean;
+}

package/dist/domain/vaults/vault-service.d.ts

@@ -0,0 +1,35 @@
+import { type CreateVaultItemRequest, type CreateVaultRequest, type ListVaultItemsQuery, type MoveVaultItemRequest, type RevealVaultFieldRequest, type RevealVaultFieldResponse, type SecretDeleteInput, type SecretDeleteOutput, type SecretGetInput, type SecretMoveInput, type SecretMoveOutput, type SecretPrincipal, type SecretSaveInput, type SecretSaveOutput, type SecretSearchInput, type SecretSearchOutput, type SessionSecretsView, type UpdateVaultItemRequest, type UpdateVaultRequest, type VaultFieldVersionMeta, type VaultItem, type VaultItemSummary, type VaultPolicy, type VaultSummary } from "@opengeni/contracts";
+import type { VaultRequestActor, VaultServiceDeps } from "./types.js";
+export interface VaultService {
+    list(actor: VaultRequestActor, workspaceId: string): Promise<VaultSummary[]>;
+    get(actor: VaultRequestActor, workspaceId: string, vaultId: string): Promise<VaultSummary>;
+    create(actor: VaultRequestActor, workspaceId: string, req: CreateVaultRequest): Promise<VaultSummary>;
+    update(actor: VaultRequestActor, workspaceId: string, vaultId: string, req: UpdateVaultRequest): Promise<VaultSummary>;
+    remove(actor: VaultRequestActor, workspaceId: string, vaultId: string, confirmName: string): Promise<void>;
+    listItems(actor: VaultRequestActor, workspaceId: string, vaultId: string, q: ListVaultItemsQuery): Promise<{
+        items: VaultItemSummary[];
+        nextCursor: string | null;
+    }>;
+    getItem(actor: VaultRequestActor, workspaceId: string, itemId: string): Promise<VaultItem>;
+    createItem(actor: VaultRequestActor, workspaceId: string, vaultId: string, req: CreateVaultItemRequest): Promise<VaultItem>;
+    updateItem(actor: VaultRequestActor, workspaceId: string, itemId: string, req: UpdateVaultItemRequest): Promise<VaultItem>;
+    archiveItem(actor: VaultRequestActor, workspaceId: string, itemId: string): Promise<void>;
+    restoreItem(actor: VaultRequestActor, workspaceId: string, itemId: string): Promise<VaultItem>;
+    deleteItemPermanently(actor: VaultRequestActor, workspaceId: string, itemId: string): Promise<void>;
+    moveItem(actor: VaultRequestActor, workspaceId: string, itemId: string, req: MoveVaultItemRequest): Promise<VaultItem>;
+    revealField(actor: VaultRequestActor, workspaceId: string, fieldId: string, req: RevealVaultFieldRequest & {
+        itemId?: string;
+    }): Promise<RevealVaultFieldResponse>;
+    listFieldVersions(actor: VaultRequestActor, workspaceId: string, fieldId: string): Promise<VaultFieldVersionMeta[]>;
+    restoreFieldVersion(actor: VaultRequestActor, workspaceId: string, itemId: string, fieldId: string, version: number): Promise<VaultItem>;
+    sessionSecrets(actor: VaultRequestActor, workspaceId: string, sessionId: string): Promise<SessionSecretsView>;
+    setSessionPolicy(actor: VaultRequestActor, workspaceId: string, sessionId: string, policy: VaultPolicy): Promise<SessionSecretsView>;
+    searchForAgent(principal: SecretPrincipal, input: SecretSearchInput): Promise<SecretSearchOutput>;
+    saveForAgent(principal: SecretPrincipal, input: SecretSaveInput): Promise<SecretSaveOutput>;
+    moveForAgent(principal: SecretPrincipal, input: SecretMoveInput): Promise<SecretMoveOutput>;
+    archiveForAgent(principal: SecretPrincipal, input: SecretDeleteInput): Promise<SecretDeleteOutput>;
+    readForAgent(principal: SecretPrincipal, input: SecretGetInput, permissions: readonly string[]): Promise<RevealVaultFieldResponse>;
+}
+/** API keys and configured keys are not people. */
+export declare function vaultActorIsApiKey(actor: VaultRequestActor): boolean;
+export declare function createVaultService(deps: VaultServiceDeps): VaultService;

package/dist/domain/voice-input-billing.d.ts

@@ -0,0 +1,77 @@
+import { type Settings, type VoiceInputPricing, type VoiceInputUsage } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+import { type TranscriptionBilling, type TranscriptionBillingContext } from "../transcription.js";
+/** Credit debit type and usage source for deployment-funded voice input. */
+export declare const VOICE_INPUT_DEBIT_TYPE = "voice_transcription_debit";
+export declare const VOICE_INPUT_SOURCE_TYPE = "voice_transcription";
+/** How the billed quantity was measured; recorded on the ledger entry. */
+export type VoiceInputBillingBasis = "provider_tokens" | "provider_duration" | "server_duration" | "reconciled_receipt";
+/**
+ * Pick the billed measurement. Provider usage wins when this deployment can
+ * price it (token usage with token rates, or a reported duration). Otherwise
+ * the duration the server measured from WAV bytes it produced bills. Every
+ * deployment-funded call carries that server duration, so an unpriced usage
+ * shape never leaves a call unbillable. A client-reported duration is never a
+ * billing input.
+ */
+export declare function voiceInputBillableUsage(input: {
+    pricing: VoiceInputPricing;
+    usage: VoiceInputUsage | null;
+    trustedDurationSeconds?: number | undefined;
+}): {
+    usage: VoiceInputUsage;
+    basis: VoiceInputBillingBasis;
+};
+/**
+ * Same admission shape as knowledge-search and session admission:
+ * voice-spendable credits (general plus signup, not model-scoped promotional
+ * credits) must be positive, the workspace/member
+ * allowance must not be exhausted, and a static monthly cost cap applies.
+ * Admission is a read, not a reservation; settlement is post-use and may take
+ * an account below zero by at most the concurrent in-flight calls.
+ */
+export declare function createVoiceInputBilling(deps: {
+    db: Database;
+    settings: Settings;
+    /** Reconciliation is best-effort at admission; failures are reported here. */
+    onReconcileError?: (error: unknown, scope: {
+        accountId: string;
+        workspaceId: string;
+    }) => void;
+    /** Minimum spacing of admission-time reconciliation per workspace (default 5 min). */
+    reconcileIntervalMilliseconds?: number;
+}): TranscriptionBilling;
+/**
+ * Two commits, in order: the `model.cost` usage receipt (Insights spend,
+ * monthly cost cap, member-allowance attribution), then the post-use credit
+ * debit. The receipt is the first-writer authority for the amount and the
+ * durable record of the charge: if the debit commit fails, the receipt stays
+ * and {@link reconcileUnsettledVoiceInputCharges} applies the same debit (same
+ * idempotency key) on the workspace's next admission. A retried unit settles
+ * exactly once at the originally recorded price.
+ */
+export declare function settleVoiceInputUsage(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    providerId: string;
+    model: string;
+    billing: TranscriptionBillingContext;
+    usage: VoiceInputUsage;
+    basis: VoiceInputBillingBasis;
+    providerCostMicros: number;
+    creditCostMicros: number;
+}): Promise<{
+    creditCostMicros: number;
+}>;
+/**
+ * Apply the debit for every voice usage receipt in this workspace whose debit
+ * never committed. Idempotent with the inline settlement (same key), bounded
+ * per call, and safe to run concurrently.
+ */
+export declare function reconcileUnsettledVoiceInputCharges(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    minAgeMilliseconds?: number;
+}): Promise<{
+    reconciled: number;
+}>;

package/dist/domain/web-search-billing.d.ts

@@ -0,0 +1,51 @@
+import { type Settings } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+/** Credit ledger type and usage source for deployment-funded web search calls. */
+export declare const WEB_SEARCH_DEBIT_TYPE = "web_search_debit";
+export declare const WEB_SEARCH_SOURCE_TYPE = "web_search";
+/** Same rule as other deployment-funded resources: Stripe or managed limits. */
+export { webSearchCreditBillingActive } from "@opengeni/config";
+/** Exact attempt that called the tool. Every charge is attributed to its turn. */
+export type WebSearchCallScope = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+};
+export type WebSearchCallCost = {
+    /** Model tool-call or Codemode operation identity, unique within the attempt. */
+    operationId: string;
+    operation: "search" | "fetch";
+    provider: string;
+    providerMicros: number;
+    creditMicros: number;
+    marginBps: number;
+    basis: "provider_reported" | "configured_price" | "list_price";
+};
+export declare class WebSearchBillingRefusedError extends Error {
+    readonly code: "insufficient_credits" | "allowance_exhausted" | "credits_disabled";
+    constructor(code: "insufficient_credits" | "allowance_exhausted" | "credits_disabled", message: string);
+}
+/** Model-facing refusal when the workspace turned Opengeni credits off. */
+export declare const WEB_SEARCH_CREDITS_DISABLED_MESSAGE = "Web search uses Opengeni credits, which are turned off in this workspace.";
+/**
+ * Admission and post-use settlement for paid web search, matching paid
+ * Knowledge queries and voice input: admission reads the workspace credit
+ * switch, general credits and the workspace/member allowance (a read, not a
+ * reservation); settlement records a durable usage receipt and the idempotent
+ * debit in one transaction. Calls that cost nothing (free providers, or
+ * billing inactive) are never refused. A workspace that turned Opengeni
+ * credits off is refused paid calls, and settlement skips the debit (and the
+ * cost receipt) for a call that was in flight when the switch turned off or
+ * that was admitted as free but reported a provider cost.
+ */
+export declare function createWebSearchBilling(deps: {
+    db: Database;
+    settings: Settings;
+}): {
+    active: boolean;
+    admit(scope: WebSearchCallScope, expectedProviderMicros: number): Promise<void>;
+    settle(scope: WebSearchCallScope, cost: WebSearchCallCost): Promise<void>;
+};
+export type WebSearchBilling = ReturnType<typeof createWebSearchBilling>;

package/dist/domain/workspace-credits.d.ts

@@ -0,0 +1,7 @@
+import { type Database } from "@opengeni/db";
+/**
+ * True when the workspace turned Opengeni credits off. Every meter that would
+ * spend credits (credit-billed models, voice, web search, knowledge
+ * embeddings) honors this one switch.
+ */
+export declare function workspaceCreditsDisabled(db: Database, workspaceId: string): Promise<boolean>;