@haven_ai/sdk 0.0.0-dev.202609041328.47fea41 → 0.0.0-dev.202609042048.ad6cc9b

package/dist/index.cjs

@@ -4542,6 +4542,104 @@ for that credential.
 var SKILL_FOLDER_NAME = "haven-pay";
 var HAVEN_SKILL_BODY_MD = HAVEN_SKILL_MD.replace(/^---\n[\s\S]*?\n---\n+/, "");
 
+// src/agent-guidance.ts
+var AGENT_SECRET_HYGIENE_SENTENCE = "Do not print private keys, API keys, credential file contents, or config secrets in chat or logs.";
+var AGENT_LOCAL_KEY_SENTENCE = "The Haven connector generates the signing key locally and sends Haven only the public signing address plus proof.";
+var AGENT_NETWORK_ACCESS_SENTENCE = "Network access is expected: this command downloads the npm package and contacts the Haven API, so if your environment is sandboxed, run it with network access enabled or request network access escalation; that changes the execution environment, not the command, and is not a third command modification.";
+var AGENT_JSON_MODE_SENTENCE = "If you are an AI agent running this command yourself rather than a human pasting it, you should append --json: the connector then emits one machine-readable, secret-free result object on stdout with progress on stderr, and returns promptly instead of blocking while it waits for the budget approval.";
+var AGENT_APPROVAL_RELAY_JSON_SENTENCE = "When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.";
+var AGENT_APPROVAL_RELAY_PROSE_SENTENCE = "If you ran the command without --json, the connector waits for the approval itself and prints its next steps when it finishes: relay the budget-approval instruction to me \u2014 return to Haven and approve this agent's budget \u2014 only if those printed next steps still ask for it. If they report the budget as already approved, there is nothing for me to approve.";
+var AGENT_COMMAND_MODIFICATION_SENTENCE = "Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.";
+var HAVEN_AGENT_RUNBOOK_MD = `# Haven for agents \u2014 set your user up to let you pay
+
+You are an AI agent whose user has no Haven account yet, or has one but has not connected you.
+
+> Links below are paths on this same host: resolve them against the URL you fetched this file from.
+
+## What Haven is, in three sentences
+
+Your user gives you a **budget on their own account** \u2014 not their wallet, and not a key to their funds. The budget is a delegation they sign, enforced on-chain: a payment over it, to the wrong recipient, or past its expiry is refused at execution time, not by a dashboard promise. Haven constructs and relays the payments; you get an agent credential and a signing key made on your machine, and your user can revoke the budget without you and without Haven.
+
+## The sequence
+
+Four of the six steps are your user's \u2014 each needs a human signature or a human decision. The rest is yours. If they already have a funded account, start at step 3.
+
+1. **HUMAN \u2014 create the account.** Name, email, password, then a passkey (Face ID / Touch ID) or a wallet. Never offer to enter any of it: you must not have their password, and the passkey is bound to their device.
+2. **HUMAN \u2014 fund it.** USDC on Base, to the address the dashboard shows.
+3. **HUMAN \u2014 create the agent, set its budget**, and paste you the **setup prompt** it hands back.
+4. **YOU \u2014 run the connector command** in that prompt (below). It makes your signing key locally, registering only the public address.
+5. **HUMAN \u2014 approve the budget** with their passkey, in the Haven tab they created the agent in: it advances to the approval step by itself once your run registers.
+6. **YOU \u2014 verify, then pay.**
+
+## Hand-off scripts
+
+Send these as your own message, \`<host>\` replaced by the host you fetched this file from. Say what you cannot do, not only what they must.
+
+**Before signup** (step 1):
+
+> I can do everything except the parts that need your signature. Please open \`<host>/signup?next=/agents&via=agent\` \u2014 name, email, password, then a passkey (Face ID / Touch ID) or a wallet. That is your account's key: I should not have it, and I will never ask for your password. Already have one? \`<host>/login?next=/agents\`.
+
+**At the passkey step:**
+
+> The passkey must be made on your own device \u2014 it is what keeps the account yours, so nobody, Haven included, can move your funds without you. If this browser cannot, open \`<host>/onboarding?next=/agents\` on your phone and finish there.
+
+**At funding** (step 2):
+
+> Your Haven account needs USDC on Base before I can pay for anything \u2014 USDC only, no ETH: Haven sponsors the gas. The dashboard shows the address to send it to; a small amount first is fine.
+
+**At the budget** (step 3):
+
+> On \`<host>/agents\`, create an agent for me and set a budget \u2014 say 25 USDC per day. That is the limit I cannot exceed. It hands back a setup prompt: paste it to me and I run it here.
+
+**At budget approval** (step 5) \u2014 the moment your run reports that approval is required, before anything else:
+
+> Setup is done on my side. Go back to the Haven tab where you created the agent \u2014 it should now be asking you to approve the budget. Approve it with your passkey; nothing can be spent until you do.
+
+## What you run
+
+The setup prompt carries a **connector command** shaped like this:
+
+\`\`\`
+npx -y @haven_ai/connect@<channel> --setup EXAMPLE-SETUP-TOKEN-NOT-REAL --api <api-url> --ack-local-tools
+\`\`\`
+
+Run the prompt's version, not this one: the token is one-time, the API URL is the backend's own, and \`<channel>\` is the npm tag your prompt names \u2014 never a tag you pick. The rules below come from that prompt, so "me" in them is your user, not Haven.
+
+- ${AGENT_JSON_MODE_SENTENCE}
+- ${AGENT_APPROVAL_RELAY_JSON_SENTENCE}
+- ${AGENT_APPROVAL_RELAY_PROSE_SENTENCE}
+- ${AGENT_COMMAND_MODIFICATION_SENTENCE}
+- ${AGENT_SECRET_HYGIENE_SENTENCE}
+
+If the approval wait times out, nothing is lost \u2014 your agent is registered and the budget is still waiting to be approved. Ask your user to finish it in that same Haven tab. You cannot send them a direct link to it: the connector's outcome carries no URL and no setup id, so do not invent one.
+
+## How to verify
+
+Call \`haven_get_agent\`, one of the Haven MCP tools the connector wires into your runtime in step 4. It returns identity plus \`spend_authority_readiness\`:
+
+- \`ready\` \u2014 a budget is live; you can pay.
+- \`needs_approval\` \u2014 the connector finished, nobody approved yet. Ask your user again, in their Haven tab; there is no queue to wait in.
+- \`revoked\` \u2014 the credential is not active; ask your user to create a new agent.
+
+\`ready\` covers hosted identity and the budget only, not your local signer. Check that with \`npx -y @haven_ai/connect@<channel> --doctor\`, the same tag your prompt named \u2014 a separate command, so the two-changes rule does not bind it.
+
+## If you cannot open a browser
+
+Nothing here needs you to. Steps 1-3 are links: hand your user the full \`<host>/\u2026\` URL and ask them to say when it is done. Step 5 is not a link \u2014 it is the tab they already have open, as above. Then poll \`haven_get_agent\` until it reads \`ready\`. Do not route around the sign-in wall \u2014 it makes the account theirs, not yours.
+
+## Vocabulary
+
+| Term | What it is |
+|---|---|
+| **setup prompt** | The text the dashboard hands your user to paste to you. Carries the command and its rules. |
+| **connector command** | The \`npx -y @haven_ai/connect@\u2026\` line you run. One-time token, one use. |
+| **agent credential** | Your API key (\`sk_agent_\u2026\`), written to \`~/.haven\`. It identifies you; alone it cannot move money. |
+| **delegate key** | Your signing key, made on this machine and never sent anywhere. |
+| **budget** | The on-chain delegation your user signed. It authorises the payment; Haven constructs and relays it. |
+
+Next: [your agent hit a 402](/402.md) \xB7 [everything agent-readable](/llms.txt)
+`;
+
 // src/node-version.ts
 var HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
 function parseNodeVersion(value) {
@@ -4625,10 +4723,17 @@ function sameUrl(a, b) {
   }
 }
 
+exports.AGENT_APPROVAL_RELAY_JSON_SENTENCE = AGENT_APPROVAL_RELAY_JSON_SENTENCE;
+exports.AGENT_APPROVAL_RELAY_PROSE_SENTENCE = AGENT_APPROVAL_RELAY_PROSE_SENTENCE;
+exports.AGENT_COMMAND_MODIFICATION_SENTENCE = AGENT_COMMAND_MODIFICATION_SENTENCE;
+exports.AGENT_JSON_MODE_SENTENCE = AGENT_JSON_MODE_SENTENCE;
+exports.AGENT_LOCAL_KEY_SENTENCE = AGENT_LOCAL_KEY_SENTENCE;
+exports.AGENT_NETWORK_ACCESS_SENTENCE = AGENT_NETWORK_ACCESS_SENTENCE;
 exports.AGENT_PAYMENT_FAILURE_CODE_VALUES = AGENT_PAYMENT_FAILURE_CODE_VALUES;
 exports.AGENT_PAYMENT_NEXT_ACTION_VALUES = AGENT_PAYMENT_NEXT_ACTION_VALUES;
 exports.AGENT_PAYMENT_PHASE_VALUES = AGENT_PAYMENT_PHASE_VALUES;
 exports.AGENT_PAYMENT_RAIL_VALUES = AGENT_PAYMENT_RAIL_VALUES;
+exports.AGENT_SECRET_HYGIENE_SENTENCE = AGENT_SECRET_HYGIENE_SENTENCE;
 exports.AgentPaymentFailureCode = AgentPaymentFailureCode;
 exports.AgentPaymentFailureCodeDescriptions = AgentPaymentFailureCodeDescriptions;
 exports.AgentPaymentFailureCodeSchema = AgentPaymentFailureCodeSchema;
@@ -4646,6 +4751,7 @@ exports.CONNECTOR_PACKAGE_NAME = CONNECTOR_PACKAGE_NAME;
 exports.DEFAULT_CONFIRMATION_TIMEOUT_MS = DEFAULT_CONFIRMATION_TIMEOUT_MS;
 exports.DISCOVERY_MAX_BYTES = DISCOVERY_MAX_BYTES;
 exports.ERC7710_ASSET_TRANSFER_METHOD = ERC7710_ASSET_TRANSFER_METHOD;
+exports.HAVEN_AGENT_RUNBOOK_MD = HAVEN_AGENT_RUNBOOK_MD;
 exports.HAVEN_CONNECTOR_CHANNEL = HAVEN_CONNECTOR_CHANNEL;
 exports.HAVEN_MINIMUM_NODE_VERSION = HAVEN_MINIMUM_NODE_VERSION;
 exports.HAVEN_SKILL_BODY_MD = HAVEN_SKILL_BODY_MD;