@purseragents/plugin-purser 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +43 -2
- package/dist/index.d.ts +20 -0
- package/dist/index.js +92 -0
- package/images/banner.jpg +0 -0
- package/images/logo.jpg +0 -0
- package/package.json +57 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Purser
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,44 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Purser for ElizaOS
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A bank account for your AI agent. The owner sets the rules, a firewall checks every payment, and the agent gets its own
|
|
4
|
+
account as tools. Made by [Purser](https://purseragents.fun).
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
npm install @purseragents/plugin-purser
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import { purserPlugin } from "@purseragents/plugin-purser";
|
|
12
|
+
|
|
13
|
+
export const character = {
|
|
14
|
+
name: "Ops",
|
|
15
|
+
plugins: [purserPlugin],
|
|
16
|
+
settings: { secrets: { PURSER_API_KEY: process.env.PURSER_API_KEY } },
|
|
17
|
+
};
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The plugin adds eight actions: `PURSER_ACCOUNT`, `PURSER_RULES`, `PURSER_CHECK_PAYMENT`, `PURSER_PAY`,
|
|
21
|
+
`PURSER_RECEIPTS`, `PURSER_PAID_FETCH`, `PURSER_PAY_INVOICE` and `PURSER_PROFIT`. Each declares its parameters, so
|
|
22
|
+
ElizaOS fills in the payee, the amount and the memo from the conversation.
|
|
23
|
+
|
|
24
|
+
The message that asked for a payment is sent along with it, so the firewall reads exactly what the agent read. A
|
|
25
|
+
hidden instruction in an email, a web page or a chat message is blocked there, and the agent answers "Blocked." with
|
|
26
|
+
the reasons and "Nothing was paid".
|
|
27
|
+
|
|
28
|
+
Settings: `PURSER_API_KEY` (required, the agent key the owner created for one account) and `PURSER_ENGINE_URL`
|
|
29
|
+
(optional, default `https://purseragents.fun`). Without a key the actions stay off.
|
|
30
|
+
|
|
31
|
+
## Getting a key
|
|
32
|
+
|
|
33
|
+
The owner opens an account for the agent on [purseragents.fun](https://purseragents.fun), sets its rules (limits per
|
|
34
|
+
payment, per day and per week, allowed payees, approvals) and creates an agent key for that one account. The key can
|
|
35
|
+
only do what the rules allow, and the owner can freeze the account or revoke the key at any time.
|
|
36
|
+
|
|
37
|
+
## Try it locally
|
|
38
|
+
|
|
39
|
+
Clone [PurserAgents/purser](https://github.com/PurserAgents/purser) and run `cd engine && npm run testmode`. It starts
|
|
40
|
+
a local chain with test money and prints an engine URL and agent keys; pass them as `baseUrl` and `apiKey`.
|
|
41
|
+
|
|
42
|
+
## License
|
|
43
|
+
|
|
44
|
+
MIT
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @purseragents/plugin-purser: give an ElizaOS agent its own Purser account.
|
|
3
|
+
*
|
|
4
|
+
* import { purserPlugin } from "@purseragents/plugin-purser";
|
|
5
|
+
*
|
|
6
|
+
* export const character = {
|
|
7
|
+
* name: "Ops",
|
|
8
|
+
* plugins: [purserPlugin],
|
|
9
|
+
* settings: { secrets: { PURSER_API_KEY: process.env.PURSER_API_KEY } },
|
|
10
|
+
* };
|
|
11
|
+
*
|
|
12
|
+
* The agent gets actions to read its account and rules, check and make payments, read receipts, fetch paid URLs
|
|
13
|
+
* (x402), pay invoices and read its profit. Every payment goes through the owner's rules and Purser's firewall
|
|
14
|
+
* first; a blocked payment is answered with the reasons, and the agent is told not to try another way.
|
|
15
|
+
*/
|
|
16
|
+
import type { Action, Plugin } from "@elizaos/core";
|
|
17
|
+
export declare const purserActions: Action[];
|
|
18
|
+
export declare const purserPlugin: Plugin;
|
|
19
|
+
export default purserPlugin;
|
|
20
|
+
export { Purser, PURSER_DEFAULT_URL } from "@purseragents/sdk";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import { Purser, purserFromSettings, purserTools, runPurserTool } from "@purseragents/sdk";
|
|
2
|
+
const setting = (runtime, key) => {
|
|
3
|
+
const v = runtime.getSetting(key);
|
|
4
|
+
return v === null || v === undefined || v === "" ? undefined : String(v);
|
|
5
|
+
};
|
|
6
|
+
/** One set of live tools per agent, made from that agent's settings, so each agent pays from its own account. */
|
|
7
|
+
const live = new WeakMap();
|
|
8
|
+
function toolFor(runtime, name) {
|
|
9
|
+
let tools = live.get(runtime);
|
|
10
|
+
if (!tools) {
|
|
11
|
+
tools = purserTools(purserFromSettings({ apiKey: setting(runtime, "PURSER_API_KEY"), baseUrl: setting(runtime, "PURSER_ENGINE_URL") }));
|
|
12
|
+
live.set(runtime, tools);
|
|
13
|
+
}
|
|
14
|
+
return tools.find((x) => x.name === name);
|
|
15
|
+
}
|
|
16
|
+
/** The tool definitions, read once; the client is made per agent from its settings. */
|
|
17
|
+
const SPECS = purserTools(new Purser({ baseUrl: "https://purseragents.fun", apiKey: "prs_spec" }));
|
|
18
|
+
const actionName = (t) => t.name.toUpperCase();
|
|
19
|
+
function parametersOf(t) {
|
|
20
|
+
return Object.entries(t.parameters.properties).map(([name, p]) => ({
|
|
21
|
+
name,
|
|
22
|
+
description: p.description,
|
|
23
|
+
required: t.parameters.required.includes(name),
|
|
24
|
+
schema: { type: p.type, description: p.description, ...(p.enum ? { enum: p.enum } : {}), ...(p.default !== undefined ? { default: p.default } : {}), ...(p.minimum !== undefined ? { minimum: p.minimum } : {}), ...(p.maximum !== undefined ? { maximum: p.maximum } : {}) },
|
|
25
|
+
}));
|
|
26
|
+
}
|
|
27
|
+
const SIMILES = {
|
|
28
|
+
purser_account: ["CHECK_BALANCE", "MY_BALANCE", "WALLET_BALANCE"],
|
|
29
|
+
purser_rules: ["SPENDING_LIMITS", "MY_BUDGET"],
|
|
30
|
+
purser_check_payment: ["CHECK_PAYMENT", "IS_PAYMENT_SAFE"],
|
|
31
|
+
purser_pay: ["PAY", "SEND_PAYMENT", "SEND_USDG", "TRANSFER"],
|
|
32
|
+
purser_receipts: ["RECEIPTS", "PAYMENT_HISTORY", "TRANSACTIONS"],
|
|
33
|
+
purser_paid_fetch: ["X402_FETCH", "PAID_FETCH", "BUY_API_CALL"],
|
|
34
|
+
purser_pay_invoice: ["PAY_INVOICE"],
|
|
35
|
+
purser_profit: ["PROFIT_AND_LOSS", "PNL", "EARNINGS"],
|
|
36
|
+
};
|
|
37
|
+
const EXAMPLES = {
|
|
38
|
+
purser_account: { user: "How much money do you have left today?" },
|
|
39
|
+
purser_pay: { user: "Pay 0x1111111111111111111111111111111111111111 2.50 USDG for the weather report", params: { to: "0x1111111111111111111111111111111111111111", amount: "2.50", memo: "weather report" } },
|
|
40
|
+
purser_receipts: { user: "What did you pay for lately?" },
|
|
41
|
+
};
|
|
42
|
+
function toAction(t) {
|
|
43
|
+
const name = actionName(t);
|
|
44
|
+
const ex = EXAMPLES[t.name];
|
|
45
|
+
return {
|
|
46
|
+
name,
|
|
47
|
+
similes: SIMILES[t.name] ?? [],
|
|
48
|
+
description: `${t.description} (Purser)`,
|
|
49
|
+
parameters: parametersOf(t),
|
|
50
|
+
tags: t.movesMoney ? ["capability:send"] : [],
|
|
51
|
+
...(t.movesMoney ? { routingHint: `money out of the agent's own Purser account -> ${name}; the owner's rules and the firewall decide, never retry a block another way` } : {}),
|
|
52
|
+
...(ex ? { exampleCalls: [{ user: ex.user, actions: [name], ...(ex.params ? { params: { [name]: ex.params } } : {}) }] } : {}),
|
|
53
|
+
validate: async (runtime) => !!setting(runtime, "PURSER_API_KEY"),
|
|
54
|
+
handler: async (runtime, message, _state, options, callback) => {
|
|
55
|
+
const o = (options ?? {});
|
|
56
|
+
const params = { ...(o.parameters ?? {}) };
|
|
57
|
+
// The firewall reads what led to a payment, so a payment always carries the message that asked for it.
|
|
58
|
+
if (t.parameters.properties.context && !params.context && message.content?.text)
|
|
59
|
+
params.context = message.content.text;
|
|
60
|
+
const missing = t.parameters.required.filter((k) => params[k] === undefined || params[k] === null || params[k] === "");
|
|
61
|
+
if (missing.length) {
|
|
62
|
+
const text = `To do that I need: ${missing.join(", ")}.`;
|
|
63
|
+
await callback?.({ text, actions: [name] });
|
|
64
|
+
return { success: false, text, error: text };
|
|
65
|
+
}
|
|
66
|
+
let text;
|
|
67
|
+
try {
|
|
68
|
+
text = await runPurserTool(toolFor(runtime, t.name), params);
|
|
69
|
+
}
|
|
70
|
+
catch (e) {
|
|
71
|
+
text = `Purser could not do that: ${e instanceof Error ? e.message : String(e)}`;
|
|
72
|
+
}
|
|
73
|
+
const ok = !text.startsWith("Purser could not");
|
|
74
|
+
await callback?.({ text, actions: [name] });
|
|
75
|
+
return { success: ok, text, userFacingText: text, data: { tool: t.name, blocked: text.startsWith("Blocked.") }, ...(ok ? {} : { error: text }) };
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
export const purserActions = SPECS.map(toAction);
|
|
80
|
+
export const purserPlugin = {
|
|
81
|
+
name: "purser",
|
|
82
|
+
description: "A bank account for the agent: balances, spending rules, payments checked by a firewall, receipts, paid URLs (x402), invoices and profit, on Purser.",
|
|
83
|
+
config: { PURSER_API_KEY: null, PURSER_ENGINE_URL: null },
|
|
84
|
+
init: async (_config, runtime) => {
|
|
85
|
+
if (!setting(runtime, "PURSER_API_KEY")) {
|
|
86
|
+
runtime.logger?.warn?.("Purser: PURSER_API_KEY is not set, so the Purser actions stay off. The owner creates the key on purseragents.fun for one account.");
|
|
87
|
+
}
|
|
88
|
+
},
|
|
89
|
+
actions: purserActions,
|
|
90
|
+
};
|
|
91
|
+
export default purserPlugin;
|
|
92
|
+
export { Purser, PURSER_DEFAULT_URL } from "@purseragents/sdk";
|
|
Binary file
|
package/images/logo.jpg
ADDED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,59 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@purseragents/plugin-purser",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Purser for ElizaOS: give your agent its own bank account, with the owner's rules and a firewall in front of every payment.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"default": "./dist/index.js"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"dist",
|
|
17
|
+
"images",
|
|
18
|
+
"README.md"
|
|
19
|
+
],
|
|
20
|
+
"keywords": [
|
|
21
|
+
"plugin",
|
|
22
|
+
"elizaos",
|
|
23
|
+
"elizaos-plugins",
|
|
24
|
+
"agent",
|
|
25
|
+
"payments",
|
|
26
|
+
"wallet",
|
|
27
|
+
"purser",
|
|
28
|
+
"x402"
|
|
29
|
+
],
|
|
30
|
+
"homepage": "https://purseragents.fun/developers",
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/PurserAgents/purser.git",
|
|
34
|
+
"directory": "packages/plugin-purser"
|
|
35
|
+
},
|
|
36
|
+
"peerDependencies": {
|
|
37
|
+
"@elizaos/core": ">=1.0.0"
|
|
38
|
+
},
|
|
39
|
+
"dependencies": {
|
|
40
|
+
"@purseragents/sdk": "^0.1.0"
|
|
41
|
+
},
|
|
42
|
+
"agentConfig": {
|
|
43
|
+
"pluginType": "elizaos:plugin:1.0.0",
|
|
44
|
+
"pluginParameters": {
|
|
45
|
+
"PURSER_API_KEY": {
|
|
46
|
+
"type": "string",
|
|
47
|
+
"description": "The agent's Purser API key (prs_...), created by the owner for one account on purseragents.fun",
|
|
48
|
+
"required": true,
|
|
49
|
+
"sensitive": true
|
|
50
|
+
},
|
|
51
|
+
"PURSER_ENGINE_URL": {
|
|
52
|
+
"type": "string",
|
|
53
|
+
"description": "The Purser engine. Default: https://purseragents.fun",
|
|
54
|
+
"required": false,
|
|
55
|
+
"sensitive": false
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|