negotium 0.22.3 → 0.22.4

package/dist/types/packages/core/src/agents/mcp-tools/request-vault.d.ts

@@ -0,0 +1,120 @@
+import { type SharedMcpTool } from "./common";
+import { type RuntimeProcessLease, type RuntimeProcessLeaseHandle } from "../../storage/runtime-process-leases";
+import { type ClaimVaultRequestGateResult, type PrepareVaultRequestGateResult, type VaultRequestGateCardUpdate } from "../../storage/vault-request-gates";
+import type { AgentKind } from "../../types";
+import type { MessageDto, TopicDto } from "../../types/api";
+export interface RequestVaultToolContext {
+    userId: string;
+    topicId: string;
+    queryId?: string;
+    agent: AgentKind;
+    model?: string;
+    threadRootId?: string;
+    /**
+     * Set when this turn's surface cannot mask text input (Telegram has no
+     * native password field, so anything a person types becomes a plaintext
+     * message that lingers in chat history). When true the tool refuses
+     * immediately and never creates a card, instead of asking for a secret on
+     * a surface that cannot protect it.
+     */
+    unsupportedSurface?: boolean;
+}
+export type AnswerVaultSecretRequestResult = {
+    ok: true;
+    queryId?: string;
+    outcome: "fulfilled" | "declined";
+    answerMessage: MessageDto;
+} | {
+    ok: false;
+    error: string;
+};
+export interface RequestVaultRuntimeHost {
+    messaging: {
+        persistence: {
+            getMessage(topicId: string, messageId: string): MessageDto | null | undefined;
+            appendMessage(message: MessageDto): void;
+        };
+        publication: {
+            publishMessage(topicId: string, message: MessageDto): void;
+            publishCardUpdate(update: VaultRequestGateCardUpdate): void;
+        };
+    };
+    topics: {
+        getTopic(topicId: string): Pick<TopicDto, "participants"> | null | undefined;
+        getConfig(topicId: string): {
+            model?: string;
+        } | undefined;
+    };
+    vault: {
+        hasKey(userId: string, key: string): boolean;
+        /** Writes the secret. Called before the gate is claimed, so a storage
+         * failure never leaves a card marked "fulfilled" without a stored value. */
+        set(userId: string, key: string, value: string, description: string): void;
+    };
+    durability: {
+        gates: {
+            prepare(args: {
+                gateId: string;
+                topicId: string;
+                queryId?: string;
+                idempotencyKey: string;
+                bodyHash: string;
+                messageId: string;
+                ownerId: string;
+                now: string;
+            }): PrepareVaultRequestGateResult;
+            claimAndAnswer(args: {
+                topicId: string;
+                messageId: string;
+                outcome: "fulfilled" | "declined";
+                userId: string;
+                ownerId: string;
+                source: string;
+                now: string;
+            }): ClaimVaultRequestGateResult;
+            cancel(topicId: string, messageId: string, ownerId: string, now: string): VaultRequestGateCardUpdate | null;
+            quarantine(gateId: string, ownerId: string, now: string): VaultRequestGateCardUpdate | null;
+            quarantineForeign(liveOwnerIds: ReadonlySet<string>, now: string): VaultRequestGateCardUpdate[];
+        };
+        processLeases: {
+            acquire(role: string, ownerId: string): RuntimeProcessLeaseHandle | null;
+            list(rolePrefix: string): RuntimeProcessLease[];
+            isAlive(lease: RuntimeProcessLease): boolean;
+            removeDead(rolePrefix: string): void;
+        };
+    };
+    runtime: {
+        ownerId: string;
+        createId(): string;
+        now(): string;
+    };
+}
+export interface RequestVaultRuntime {
+    startGateOwner(): void;
+    stopGateOwner(): void;
+    reconcilePendingGates(): number;
+    answerPendingRequest(topicId: string, messageId: string, userId: string, value: string | null): AnswerVaultSecretRequestResult;
+    cancelPendingRequests(topicId: string, queryId: string): void;
+    createToolDefinition(ctx: RequestVaultToolContext): SharedMcpTool;
+}
+/**
+ * Create an isolated request-vault-secret lifecycle over host-provided
+ * messaging, topic, vault, durability, and runtime services. Mirrors
+ * `createAskUserRuntime`'s durable-gate shape, but the thing being
+ * exchanged is "did the user supply a value", never the value itself.
+ */
+export declare function createRequestVaultRuntime(host: RequestVaultRuntimeHost): RequestVaultRuntime;
+export declare const defaultRequestVaultDurabilityHost: RequestVaultRuntimeHost["durability"];
+export declare function startRequestVaultGateOwner(): void;
+export declare function stopRequestVaultGateOwner(): void;
+export declare function reconcilePendingRequestVaultGates(): number;
+/**
+ * Host-neutral answer path for pending vault-request cards. Terminal and
+ * Otium should call this rather than reimplementing pending-map and
+ * persistence ordering. `value: null` means the user declined; any other
+ * string is the secret, stored via `vaultSet` before the gate is claimed,
+ * and never echoed back in the result.
+ */
+export declare function answerPendingVaultSecretRequest(topicId: string, messageId: string, userId: string, value: string | null): AnswerVaultSecretRequestResult;
+export declare function cancelPendingVaultSecretRequests(topicId: string, queryId: string): void;
+export declare function createRequestVaultToolDefinition(ctx: RequestVaultToolContext): SharedMcpTool;

package/dist/types/packages/core/src/storage/api-messages.d.ts

@@ -20,6 +20,7 @@ export interface ApiMessageRow {
     ask_user_question: string | null;
     tell_card: string | null;
     subagent_card: string | null;
+    vault_secret_request: string | null;
     mentions: string | null;
     thread_root_id: string | null;
     created_at: string;

package/dist/types/packages/core/src/storage/vault-request-gates.d.ts

@@ -0,0 +1,69 @@
+import type { VaultSecretRequestDto } from "../types/api";
+export type VaultRequestGateState = "pending" | "claimed" | "answered" | "cancelled" | "quarantined";
+export interface VaultRequestGateRecord {
+    gateId: string;
+    topicId: string;
+    queryId?: string;
+    idempotencyKey: string;
+    bodyHash: string;
+    messageId: string;
+    ownerId: string;
+    state: VaultRequestGateState;
+    outcome?: "fulfilled" | "declined";
+    answeredBy?: string;
+}
+export interface VaultRequestGateCardUpdate {
+    topicId: string;
+    messageId: string;
+    vaultSecretRequest: VaultSecretRequestDto;
+    editedAt: string;
+}
+export type PrepareVaultRequestGateResult = {
+    outcome: "created";
+    gate: VaultRequestGateRecord;
+} | {
+    outcome: "pending";
+    gate: VaultRequestGateRecord;
+} | {
+    outcome: "replay";
+    gate: VaultRequestGateRecord;
+} | {
+    outcome: "conflict";
+    gate: VaultRequestGateRecord;
+};
+export declare function prepareVaultRequestGate(args: {
+    gateId: string;
+    topicId: string;
+    queryId?: string;
+    idempotencyKey: string;
+    bodyHash: string;
+    messageId: string;
+    ownerId: string;
+    now: string;
+}): PrepareVaultRequestGateResult;
+export declare function quarantineVaultRequestGate(gateId: string, ownerId: string, now?: string): VaultRequestGateCardUpdate | null;
+export declare function quarantineForeignVaultRequestGates(liveOwnerIds: ReadonlySet<string>, now?: string): VaultRequestGateCardUpdate[];
+export type ClaimVaultRequestGateResult = {
+    outcome: "claimed";
+    gate: VaultRequestGateRecord;
+    vaultSecretRequest: VaultSecretRequestDto;
+    editedAt: string;
+} | {
+    outcome: "unavailable";
+};
+/**
+ * Claim the gate and mark the card's outcome. This never touches the secret
+ * value itself — the caller is responsible for writing to the vault (via
+ * `vaultSet`) *before* calling this, so the card only ever reflects
+ * "fulfilled"/"declined", never the plaintext.
+ */
+export declare function claimVaultRequestGateAndAnswer(args: {
+    topicId: string;
+    messageId: string;
+    outcome: "fulfilled" | "declined";
+    userId: string;
+    ownerId: string;
+    source: string;
+    now: string;
+}): ClaimVaultRequestGateResult;
+export declare function cancelVaultRequestGate(topicId: string, messageId: string, ownerId: string, now?: string): VaultRequestGateCardUpdate | null;

package/dist/types/packages/core/src/types/api.d.ts

@@ -249,8 +249,9 @@ export interface MessageDto {
     threadLastReplyAt?: string;
     /** Emoji reactions, one entry per (user, emoji). */
     reactions?: ReactionDto[];
-    kind?: "message" | "system" | "tool" | "ask_user_question" | "subagent" | "tell";
+    kind?: "message" | "system" | "tool" | "ask_user_question" | "vault_secret_request" | "subagent" | "tell";
     askUserQuestion?: AskUserQuestionDto;
+    vaultSecretRequest?: VaultSecretRequestDto;
     subagentCard?: SubagentCardDto;
     tellCard?: TellCardDto;
     createdAt: string;
@@ -264,6 +265,18 @@ export interface AskUserQuestionDto {
     selectedLabel?: string;
     expired?: boolean;
 }
+/**
+ * Blocking card for `request_vault_secret`: the agent proposes a key and
+ * description, a person types only the value on a surface that can mask
+ * input, and the plaintext never flows back through this DTO, a tool
+ * result, or chat history — only the outcome does.
+ */
+export interface VaultSecretRequestDto {
+    key: string;
+    description?: string;
+    status: "pending" | "fulfilled" | "declined" | "expired";
+    answeredBy?: string;
+}
 /** Structured cross-session delivery. Never inferred from system-message text. */
 export interface TellCardDto {
     fromLabel: string;
@@ -461,6 +474,7 @@ export type WsServerMessage = {
     editedAt?: string;
     usage?: MessageTokenUsage;
     askUserQuestion?: AskUserQuestionDto;
+    vaultSecretRequest?: VaultSecretRequestDto;
     subagentCard?: SubagentCardDto;
 } | {
     type: "reaction_update";

package/dist/types/packages/core/src/version.d.ts

@@ -1 +1 @@
-export declare const NEGOTIUM_VERSION = "0.22.3";
+export declare const NEGOTIUM_VERSION = "0.22.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "negotium",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "type": "module",
   "description": "Install the Negotium multi-agent runtime and CLI with one package",
   "license": "Apache-2.0",