@kybernesis/vault 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { listVaultTool, fillFromVaultTool } from "./tools.js";
 export { VAULT_INSTRUCTIONS } from "./instructions.js";
 export { listItems, materialize, personFromContext, sameSite, valuesOf, NO_PERSON, type MaterializedItem, type PrincipalContext, type VaultClientOptions, type VaultKind, type VaultSummary, } from "./client.js";
+export { vaultItemAsk, interpretVaultAnswer, vaultItemPrompt, parseVaultItemPrompt, savedAnswer, REQUEST_VAULT_ITEM_DESCRIPTION, VAULT_ITEM_MARKER, SAVED_PREFIX, type VaultItemAsk, type VaultRequestOutcome } from "./request.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { listVaultTool, fillFromVaultTool } from "./tools.js";
 export { VAULT_INSTRUCTIONS } from "./instructions.js";
 export { listItems, materialize, personFromContext, sameSite, valuesOf, NO_PERSON, } from "./client.js";
+export { vaultItemAsk, interpretVaultAnswer, vaultItemPrompt, parseVaultItemPrompt, savedAnswer, REQUEST_VAULT_ITEM_DESCRIPTION, VAULT_ITEM_MARKER, SAVED_PREFIX } from "./request.js";

package/dist/instructions.d.ts

@@ -1 +1 @@
-export declare const VAULT_INSTRUCTIONS = "## The person's vault\n\nThe person can save logins, cards and addresses in KYBER Studio (Settings \u2192 Vault). You can use them on your own computer without ever seeing them:\n\n- `list_vault` with the page URL tells you what applies: labels, usernames, a card's brand and last four. That is all you get.\n- `fill_from_vault` types an item into the form you are looking at. You give the item id and the CSS selector of each field; the values go straight into the page. Then take a screenshot and check before submitting.\n\nRules: a login only fills on the site it was saved for; if the tool refuses, say so rather than retyping anything by hand. A card asks the person for approval every time. If a site asks for a code or a second factor, stop and tell the person what is on the screen \u2014 they can take over your screen. Never ask the person to paste a password into chat; point them to the vault instead.\n";
+export declare const VAULT_INSTRUCTIONS = "## The person's vault\n\nThe person can save logins, cards and addresses in KYBER Studio (Settings \u2192 Vault). You can use them on your own computer without ever seeing them:\n\n- `list_vault` with the page URL tells you what applies: labels, usernames, a card's brand and last four. That is all you get.\n- `fill_from_vault` types an item into the form you are looking at. You give the item id and the CSS selector of each field; the values go straight into the page. Then take a screenshot and check before submitting.\n\n- When `list_vault` has nothing for the site, call `request_vault_item` with the kind, the site and what you are doing. The turn pauses. If it comes back `saved`, call `fill_from_vault` with the item id. If `manual`, the person is typing on your screen: watch with screenshots and continue once the form is filled, without touching the fields. If `cancelled`, stop.\n\nRules: a login only fills on the site it was saved for; if the tool refuses, say so rather than retyping anything by hand. A card asks the person for approval every time. If a site asks for a code or a second factor, stop and tell the person what is on the screen \u2014 they can take over your screen. Never ask the person to paste a password into chat; point them to the vault instead.\n";

package/dist/instructions.js

@@ -5,5 +5,7 @@ The person can save logins, cards and addresses in KYBER Studio (Settings → Va
 - \`list_vault\` with the page URL tells you what applies: labels, usernames, a card's brand and last four. That is all you get.
 - \`fill_from_vault\` types an item into the form you are looking at. You give the item id and the CSS selector of each field; the values go straight into the page. Then take a screenshot and check before submitting.
 
+- When \`list_vault\` has nothing for the site, call \`request_vault_item\` with the kind, the site and what you are doing. The turn pauses. If it comes back \`saved\`, call \`fill_from_vault\` with the item id. If \`manual\`, the person is typing on your screen: watch with screenshots and continue once the form is filled, without touching the fields. If \`cancelled\`, stop.
+
 Rules: a login only fills on the site it was saved for; if the tool refuses, say so rather than retyping anything by hand. A card asks the person for approval every time. If a site asks for a code or a second factor, stop and tell the person what is on the screen — they can take over your screen. Never ask the person to paste a password into chat; point them to the vault instead.
 `;

package/dist/request.d.ts

@@ -0,0 +1,65 @@
+import type { VaultKind } from "./client.js";
+/**
+ * A structured question a client can render as a form.
+ *
+ * eve's `ctx.ask` carries a prompt and options; nothing else. So the first
+ * line of the prompt is a marker a Kybernesis client recognises
+ * (`[kyb:vault-item] {json}`) and the rest is the plain question every other
+ * surface shows. Studio draws a form and answers with the saved item's id;
+ * iMessage shows the text and two buttons. The secret never reaches this
+ * tool: the client stores it in the control plane itself and hands back an id.
+ */
+export declare const VAULT_ITEM_MARKER = "[kyb:vault-item]";
+export interface VaultItemAsk {
+    readonly kind: VaultKind;
+    readonly site?: string;
+    readonly label?: string;
+    readonly reason?: string;
+    /** Which fields the page wants, when the agent can tell (e.g. ["username","password"] or ["number","cvc","expiration","name"]). */
+    readonly fields?: readonly string[];
+}
+export declare function vaultItemPrompt(ask: VaultItemAsk): string;
+/** The marker's payload, if a prompt carries one. Clients call this. */
+export declare function parseVaultItemPrompt(prompt: string): {
+    ask: VaultItemAsk;
+    text: string;
+} | null;
+/** A client that saved the item answers with this; the tool reads the id out of it. */
+export declare const SAVED_PREFIX = "vault:";
+export declare function savedAnswer(itemId: string): string;
+export type VaultRequestOutcome = {
+    status: "saved";
+    item_id: string;
+    note: string;
+} | {
+    status: "manual";
+    note: string;
+} | {
+    status: "cancelled";
+    note: string;
+} | {
+    status: "unavailable";
+    note: string;
+};
+/** What the agent's tool file passes to `ctx.ask`. The tool itself must be authored in `agent/tools/` — eve compiles `"use workflow"` from source, so a package cannot ship it. */
+export declare function vaultItemAsk(input: VaultItemAsk): {
+    prompt: string;
+    display: "select";
+    allowFreeform: boolean;
+    options: ({
+        id: string;
+        label: string;
+        style?: undefined;
+    } | {
+        id: string;
+        label: string;
+        style: "danger";
+    })[];
+};
+/** Turn the person's answer into the tool's result. */
+export declare function interpretVaultAnswer(answer: {
+    status: string;
+    optionId?: string;
+    text?: string;
+}): VaultRequestOutcome;
+export declare const REQUEST_VAULT_ITEM_DESCRIPTION = "Ask the person for a login, card, address or contact you need but could not find in their vault (use list_vault first). The turn pauses until they answer. They can add it to the vault (you get an item id to use with fill_from_vault), take over your screen to type it themselves, or cancel. Never ask for secrets in chat; use this.";

package/dist/request.js

@@ -0,0 +1,64 @@
+/**
+ * A structured question a client can render as a form.
+ *
+ * eve's `ctx.ask` carries a prompt and options; nothing else. So the first
+ * line of the prompt is a marker a Kybernesis client recognises
+ * (`[kyb:vault-item] {json}`) and the rest is the plain question every other
+ * surface shows. Studio draws a form and answers with the saved item's id;
+ * iMessage shows the text and two buttons. The secret never reaches this
+ * tool: the client stores it in the control plane itself and hands back an id.
+ */
+export const VAULT_ITEM_MARKER = "[kyb:vault-item]";
+export function vaultItemPrompt(ask) {
+    const what = ask.kind === "login" ? "a login" : ask.kind === "card" ? "a card" : ask.kind === "address" ? "an address" : "contact details";
+    const where = ask.site ? ` for ${ask.site}` : "";
+    const why = ask.reason ? ` ${ask.reason.trim().replace(/\.?$/, ".")}` : "";
+    return `${VAULT_ITEM_MARKER} ${JSON.stringify(ask)}\nI need ${what}${where} and there is nothing in your vault for it.${why} Add it to your vault and I will use it without seeing it, or take over my screen and type it yourself.`;
+}
+/** The marker's payload, if a prompt carries one. Clients call this. */
+export function parseVaultItemPrompt(prompt) {
+    if (!prompt.startsWith(VAULT_ITEM_MARKER))
+        return null;
+    const nl = prompt.indexOf("\n");
+    const head = nl === -1 ? prompt : prompt.slice(0, nl);
+    try {
+        const ask = JSON.parse(head.slice(VAULT_ITEM_MARKER.length).trim());
+        return { ask, text: nl === -1 ? "" : prompt.slice(nl + 1) };
+    }
+    catch {
+        return null;
+    }
+}
+/** A client that saved the item answers with this; the tool reads the id out of it. */
+export const SAVED_PREFIX = "vault:";
+export function savedAnswer(itemId) {
+    return `${SAVED_PREFIX}${itemId}`;
+}
+/** What the agent's tool file passes to `ctx.ask`. The tool itself must be authored in `agent/tools/` — eve compiles `"use workflow"` from source, so a package cannot ship it. */
+export function vaultItemAsk(input) {
+    return {
+        prompt: vaultItemPrompt(input),
+        display: "select",
+        allowFreeform: true,
+        options: [
+            { id: "manual", label: "I'll type it myself on your screen" },
+            { id: "cancel", label: "Cancel", style: "danger" },
+        ],
+    };
+}
+/** Turn the person's answer into the tool's result. */
+export function interpretVaultAnswer(answer) {
+    if (answer.status === "unavailable")
+        return { status: "unavailable", note: "No one can answer here (an unattended run). Stop and say what you need." };
+    if (answer.status === "dismissed" || answer.optionId === "cancel")
+        return { status: "cancelled", note: "The person cancelled. Do not try another way to get these details." };
+    if (answer.optionId === "manual")
+        return { status: "manual", note: "The person will type it on your screen. Take a screenshot every ~20 seconds until the form is filled or the page changes, then continue; do not touch the fields." };
+    const text = (answer.text ?? "").trim();
+    if (text.startsWith(SAVED_PREFIX)) {
+        const id = text.slice(SAVED_PREFIX.length).trim();
+        return { status: "saved", item_id: id, note: `Saved to the vault as ${id}. Call fill_from_vault with this id and the field selectors.` };
+    }
+    return { status: "cancelled", note: text ? `The person replied: ${text.slice(0, 200)}` : "No usable answer." };
+}
+export const REQUEST_VAULT_ITEM_DESCRIPTION = "Ask the person for a login, card, address or contact you need but could not find in their vault (use list_vault first). The turn pauses until they answer. They can add it to the vault (you get an item id to use with fill_from_vault), take over your screen to type it themselves, or cancel. Never ask for secrets in chat; use this.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/vault",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The person's password and card vault, usable by their eve agent on its own computer: the agent sees labels and handles, the control plane holds the secrets, and a fill tool types them into the page so they are never in the transcript.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,7 +15,12 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./ask": {
+      "types": "./dist/request.d.ts",
+      "import": "./dist/request.js",
+      "default": "./dist/request.js"
+    }
   },
   "files": [
     "dist",