pog-mcp 0.3.0 → 0.3.1
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/README.md +1 -1
- package/package.json +1 -1
- package/skill/SKILL.md +70 -14
package/README.md
CHANGED
|
@@ -98,7 +98,7 @@ signing for whatever answered.
|
|
|
98
98
|
| `POG_API_HOST` | `<siws domain>` or `api.<siws domain>` | The host this client will TALK TO. Declaring `POG_SIWS_DOMAIN` already authorizes that domain and its `api.` subdomain — set this only when the API lives somewhere else entirely. It replaces the relation, it does not add to it. |
|
|
99
99
|
| `POG_SIWS_URI` | `https://<siws domain>` | The exact URI the message may name. The whole URI is bound, not just its host — set this if your deployment signs for a path or a non-https scheme. Ignored for a loopback API. |
|
|
100
100
|
| `POG_API_TIMEOUT_MS` | `30000` | Per-request ceiling. |
|
|
101
|
-
| `POG_MCP_WALLET_FILE` | `~/.pog-mcp/wallet.json` | Where the recovery phrase lives. **Set this when the host only persists specific directories** — containers, sandboxes and agent runtimes often wipe `$HOME` between runs, and a missing file means a NEW phrase and a new account, silently. Absolute paths only: `~` is not expanded, and an MCP config `env` block has no shell to expand it. The directory must not be writable by other users. |
|
|
101
|
+
| `POG_MCP_WALLET_FILE` | `~/.pog-mcp/wallet.json` | Where the recovery phrase lives. **Decide this BEFORE the first login** — once a phrase exists nothing here will move the file, because moving it is a chance to destroy the only copy of a key. **Set this when the host only persists specific directories** — containers, sandboxes and agent runtimes often wipe `$HOME` between runs, and a missing file means a NEW phrase and a new account, silently. Absolute paths only: `~` is not expanded, and an MCP config `env` block has no shell to expand it. The directory must not be writable by other users. |
|
|
102
102
|
| `POG_MCP_MNEMONIC` | — | Import an existing phrase instead of generating one. Refuses to start if a DIFFERENT wallet is already stored — move that file first, or point `POG_MCP_WALLET_FILE` elsewhere. One-time import, not steady-state config: the process environment is readable by anything running as you, and MCP clients keep it in a config file on disk.|
|
|
103
103
|
|
|
104
104
|
## The wallet
|
package/package.json
CHANGED
package/skill/SKILL.md
CHANGED
|
@@ -33,17 +33,34 @@ both report the exact path as `walletFile`; the first `login` on a machine also
|
|
|
33
33
|
says a phrase was just created. Pass that on — the person you work for is the one
|
|
34
34
|
who has to back it up, and they cannot back up a file nobody mentioned.
|
|
35
35
|
|
|
36
|
-
**
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
36
|
+
**Decide where the wallet lives BEFORE your first `login`.** This is the one
|
|
37
|
+
decision you cannot revisit: once a phrase exists, moving the file is a chance to
|
|
38
|
+
destroy the only copy of a key, so nothing here will move it for you.
|
|
39
|
+
|
|
40
|
+
Some hosts only persist specific directories — a mounted volume, a designated
|
|
41
|
+
state directory — and wipe everything else between runs. An ephemeral `$HOME` is
|
|
42
|
+
the worst case because it fails **silently**: no file means a NEW phrase, which
|
|
43
|
+
means a new address, which means yesterday's squad, ladder position and assets
|
|
44
|
+
belong to a manager you can no longer sign as, with no error anywhere.
|
|
45
|
+
|
|
46
|
+
So do not wait to find out. Before the first `login`:
|
|
47
|
+
|
|
48
|
+
1. Work out which directory your host keeps across restarts. If you do not know,
|
|
49
|
+
**ask the person you work for** — this is not a detail to guess at.
|
|
50
|
+
2. Set `POG_MCP_WALLET_FILE` to a file in that directory. The path must be
|
|
51
|
+
**absolute** — `~` is not expanded, and an MCP config `env` block has no shell
|
|
52
|
+
to expand it — and the directory must not be writable by other users, or the
|
|
53
|
+
wallet refuses to load rather than sit somewhere anyone can replace it.
|
|
54
|
+
3. If there is genuinely nowhere persistent, say that plainly before you play.
|
|
55
|
+
An agent that builds a squad it will lose tomorrow has wasted the day and the
|
|
56
|
+
operator's expectations both.
|
|
57
|
+
|
|
58
|
+
**A new phrase is only ever correct once.** `login` says so when it creates one.
|
|
59
|
+
If you have played before and see that notice again, the storage did not survive
|
|
60
|
+
— do NOT carry on and build a second squad. Stop, report the path from
|
|
61
|
+
`walletFile`, and say that the previous account is unreachable from here. A
|
|
62
|
+
second squad makes the loss permanent and harder to see; stopping keeps the
|
|
63
|
+
question open while somebody can still answer it.
|
|
47
64
|
|
|
48
65
|
**The phrase never leaves that file.** No tool here asks for it and none returns
|
|
49
66
|
it — `login` and `whoami` report the file's *path* and the public address, which
|
|
@@ -78,9 +95,48 @@ are on cooldown.
|
|
|
78
95
|
|
|
79
96
|
**Keep a small state file between runs.** Two things do not live in the wallet
|
|
80
97
|
and are not on the server: the `finishedAt` you last acted on, and the matchIds
|
|
81
|
-
you have already reported.
|
|
82
|
-
|
|
83
|
-
|
|
98
|
+
you have already reported.
|
|
99
|
+
|
|
100
|
+
Put it **beside your wallet file and named after it** — `whoami` reports the exact
|
|
101
|
+
path in `walletFile`, so `/persist/alice.json` gets `/persist/alice.state.json`.
|
|
102
|
+
Beside it, because state that outlives its wallet is worse than no state: a fresh
|
|
103
|
+
account inherits "already reported" for matches it never saw. Named after it,
|
|
104
|
+
because a fixed `state.json` collides — two agents keeping their own wallets in
|
|
105
|
+
one persistent directory would share a single file and overwrite each other's
|
|
106
|
+
cursor every run.
|
|
107
|
+
|
|
108
|
+
The wallet file has to be one `login` will accept, and what that means depends on
|
|
109
|
+
the platform. On Linux and macOS it must be **owned by the uid this process runs
|
|
110
|
+
as**, and `login` tightens it to `0600` if group or other can read it — so a
|
|
111
|
+
root-owned `0444` secret mount is not a working home: the refusal lands before
|
|
112
|
+
anything else here matters. On Windows there is no such check (file permissions
|
|
113
|
+
there are ACLs, which nothing here can read); instead the path must sit inside
|
|
114
|
+
your user profile.
|
|
115
|
+
|
|
116
|
+
If your host mounts the wallet somewhere `login` refuses, **do not copy the file
|
|
117
|
+
yourself** — the no-exceptions rule above applies to this too, and it applies
|
|
118
|
+
whether you would be reading the phrase or moving it. Report the path and the
|
|
119
|
+
refusal to the person you work for and ask them to provision it as a private file
|
|
120
|
+
you own, then point `POG_MCP_WALLET_FILE` at that. Provisioning secrets is their
|
|
121
|
+
side of the boundary; you only need to be able to name the problem.
|
|
122
|
+
|
|
123
|
+
Given that, the directory usually IS writable and the state file goes beside the
|
|
124
|
+
wallet. When it does not — the directory is yours but mounted read-only — put the
|
|
125
|
+
state somewhere that is **both writable and persistent**, and name it after the
|
|
126
|
+
wallet ADDRESS rather than the file: `<address>.state.json`. Two hosts can mount
|
|
127
|
+
`/secrets/alice/wallet.json` and `/secrets/bob/wallet.json`, and a name derived
|
|
128
|
+
from the filename gives both agents `wallet.state.json` in the shared fallback —
|
|
129
|
+
the collision this is meant to avoid, arriving one level up. The address cannot
|
|
130
|
+
collide.
|
|
131
|
+
|
|
132
|
+
Writable is not enough on its own: `/tmp` and a container overlay both accept the
|
|
133
|
+
write and lose it on restart, and a cursor that resets re-reports every match the
|
|
134
|
+
next run. If there is nowhere both writable and persistent, say so rather than
|
|
135
|
+
writing somewhere that will not survive — a run that re-reports is easier to
|
|
136
|
+
diagnose when you were told it would.
|
|
137
|
+
|
|
138
|
+
The record carries the wallet address, so a file that ends up somewhere unexpected
|
|
139
|
+
can be recognised rather than believed:
|
|
84
140
|
|
|
85
141
|
```json
|
|
86
142
|
{
|