@poa-box/agent 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.
Files changed (139) hide show
  1. package/.env.agent.template +20 -0
  2. package/README.md +46 -0
  3. package/brain/Config/agent-config.json +14 -0
  4. package/brain/Config/brain-allowlist.json +20 -0
  5. package/brain/Identity/goals.template.md +23 -0
  6. package/brain/Identity/how-i-think.md +406 -0
  7. package/brain/Identity/who-i-am.template.md +34 -0
  8. package/brain/Knowledge/BOOTSTRAP.md +66 -0
  9. package/brain/Knowledge/audit-corpus-index.json +406 -0
  10. package/brain/Knowledge/discussions.json +245 -0
  11. package/brain/Knowledge/pop.brain.brainstorms.generated.md +48 -0
  12. package/brain/Knowledge/pop.brain.brainstorms.genesis.bin +0 -0
  13. package/brain/Knowledge/pop.brain.heuristics.snapshot.bin +0 -0
  14. package/brain/Knowledge/pop.brain.projects.generated.md +16 -0
  15. package/brain/Knowledge/pop.brain.projects.genesis.bin +0 -0
  16. package/brain/Knowledge/pop.brain.retros.generated.md +91 -0
  17. package/brain/Knowledge/pop.brain.retros.genesis.bin +0 -0
  18. package/brain/Knowledge/pop.brain.shared.generated.md +3811 -0
  19. package/brain/Knowledge/pop.brain.shared.genesis.bin +0 -0
  20. package/brain/Knowledge/projects.md +181 -0
  21. package/brain/Knowledge/risk-framework.md +90 -0
  22. package/brain/Knowledge/shared.md +416 -0
  23. package/brain/Knowledge/sprint-priorities.md +439 -0
  24. package/brain/Memory/.gitkeep +0 -0
  25. package/dist/commands/agent/daily-digest.d.ts +24 -0
  26. package/dist/commands/agent/daily-digest.js +336 -0
  27. package/dist/commands/agent/delegate.d.ts +12 -0
  28. package/dist/commands/agent/delegate.js +91 -0
  29. package/dist/commands/agent/deploy-to-org.d.ts +20 -0
  30. package/dist/commands/agent/deploy-to-org.js +154 -0
  31. package/dist/commands/agent/index.d.ts +2 -0
  32. package/dist/commands/agent/index.js +27 -0
  33. package/dist/commands/agent/init.d.ts +19 -0
  34. package/dist/commands/agent/init.js +303 -0
  35. package/dist/commands/agent/onboard.d.ts +22 -0
  36. package/dist/commands/agent/onboard.js +192 -0
  37. package/dist/commands/agent/paymaster-status.d.ts +14 -0
  38. package/dist/commands/agent/paymaster-status.js +130 -0
  39. package/dist/commands/agent/register.d.ts +21 -0
  40. package/dist/commands/agent/register.js +116 -0
  41. package/dist/commands/agent/setup-sponsorship.d.ts +22 -0
  42. package/dist/commands/agent/setup-sponsorship.js +154 -0
  43. package/dist/commands/agent/status.d.ts +12 -0
  44. package/dist/commands/agent/status.js +171 -0
  45. package/dist/commands/agent/triage.d.ts +12 -0
  46. package/dist/commands/agent/triage.js +503 -0
  47. package/dist/commands/brain/advance-stage.d.ts +42 -0
  48. package/dist/commands/brain/advance-stage.js +206 -0
  49. package/dist/commands/brain/allowlist.d.ts +30 -0
  50. package/dist/commands/brain/allowlist.js +274 -0
  51. package/dist/commands/brain/append-lesson.d.ts +55 -0
  52. package/dist/commands/brain/append-lesson.js +245 -0
  53. package/dist/commands/brain/brainstorm.d.ts +154 -0
  54. package/dist/commands/brain/brainstorm.js +573 -0
  55. package/dist/commands/brain/daemon.d.ts +31 -0
  56. package/dist/commands/brain/daemon.js +348 -0
  57. package/dist/commands/brain/doctor.d.ts +27 -0
  58. package/dist/commands/brain/doctor.js +497 -0
  59. package/dist/commands/brain/edit-lesson.d.ts +51 -0
  60. package/dist/commands/brain/edit-lesson.js +248 -0
  61. package/dist/commands/brain/import-snapshot.d.ts +68 -0
  62. package/dist/commands/brain/import-snapshot.js +177 -0
  63. package/dist/commands/brain/index.d.ts +2 -0
  64. package/dist/commands/brain/index.js +67 -0
  65. package/dist/commands/brain/list.d.ts +21 -0
  66. package/dist/commands/brain/list.js +83 -0
  67. package/dist/commands/brain/migrate-projects.d.ts +44 -0
  68. package/dist/commands/brain/migrate-projects.js +209 -0
  69. package/dist/commands/brain/migrate.d.ts +74 -0
  70. package/dist/commands/brain/migrate.js +306 -0
  71. package/dist/commands/brain/new-project.d.ts +53 -0
  72. package/dist/commands/brain/new-project.js +226 -0
  73. package/dist/commands/brain/read.d.ts +24 -0
  74. package/dist/commands/brain/read.js +81 -0
  75. package/dist/commands/brain/remove-lesson.d.ts +47 -0
  76. package/dist/commands/brain/remove-lesson.js +206 -0
  77. package/dist/commands/brain/remove-project.d.ts +36 -0
  78. package/dist/commands/brain/remove-project.js +177 -0
  79. package/dist/commands/brain/retro-file-tasks.d.ts +84 -0
  80. package/dist/commands/brain/retro-file-tasks.js +372 -0
  81. package/dist/commands/brain/retro-list.d.ts +28 -0
  82. package/dist/commands/brain/retro-list.js +125 -0
  83. package/dist/commands/brain/retro-mark-change.d.ts +58 -0
  84. package/dist/commands/brain/retro-mark-change.js +176 -0
  85. package/dist/commands/brain/retro-remove.d.ts +36 -0
  86. package/dist/commands/brain/retro-remove.js +142 -0
  87. package/dist/commands/brain/retro-respond.d.ts +56 -0
  88. package/dist/commands/brain/retro-respond.js +250 -0
  89. package/dist/commands/brain/retro-show.d.ts +23 -0
  90. package/dist/commands/brain/retro-show.js +100 -0
  91. package/dist/commands/brain/retro-start.d.ts +55 -0
  92. package/dist/commands/brain/retro-start.js +311 -0
  93. package/dist/commands/brain/search.d.ts +48 -0
  94. package/dist/commands/brain/search.js +190 -0
  95. package/dist/commands/brain/snapshot.d.ts +32 -0
  96. package/dist/commands/brain/snapshot.js +243 -0
  97. package/dist/commands/brain/status.d.ts +15 -0
  98. package/dist/commands/brain/status.js +166 -0
  99. package/dist/commands/brain/subscribe.d.ts +28 -0
  100. package/dist/commands/brain/subscribe.js +90 -0
  101. package/dist/commands/brain/tag.d.ts +46 -0
  102. package/dist/commands/brain/tag.js +192 -0
  103. package/dist/index.d.ts +17 -0
  104. package/dist/index.js +22 -0
  105. package/dist/lib/brain-daemon.d.ts +126 -0
  106. package/dist/lib/brain-daemon.js +811 -0
  107. package/dist/lib/brain-membership.d.ts +58 -0
  108. package/dist/lib/brain-membership.js +115 -0
  109. package/dist/lib/brain-migrate-projects.d.ts +43 -0
  110. package/dist/lib/brain-migrate-projects.js +247 -0
  111. package/dist/lib/brain-migrate.d.ts +77 -0
  112. package/dist/lib/brain-migrate.js +328 -0
  113. package/dist/lib/brain-ops.d.ts +271 -0
  114. package/dist/lib/brain-ops.js +571 -0
  115. package/dist/lib/brain-paths.d.ts +15 -0
  116. package/dist/lib/brain-paths.js +33 -0
  117. package/dist/lib/brain-projections.d.ts +216 -0
  118. package/dist/lib/brain-projections.js +829 -0
  119. package/dist/lib/brain-schemas.d.ts +36 -0
  120. package/dist/lib/brain-schemas.js +316 -0
  121. package/dist/lib/brain-signing.d.ts +103 -0
  122. package/dist/lib/brain-signing.js +256 -0
  123. package/dist/lib/brain.d.ts +198 -0
  124. package/dist/lib/brain.js +1057 -0
  125. package/dist/pop-agent.d.ts +1 -0
  126. package/dist/pop-agent.js +18 -0
  127. package/docs/agent.md +126 -0
  128. package/docs/agents/brain-anti-entropy.md +127 -0
  129. package/docs/agents/brain-cross-device-onboarding.md +210 -0
  130. package/docs/agents/brain-cross-machine-smoke.md +241 -0
  131. package/docs/agents/brain-layer-setup.md +725 -0
  132. package/docs/agents/offboarding-protocol.md +188 -0
  133. package/docs/agents/onboarding-protocol.md +243 -0
  134. package/docs/agents/running-an-agent.md +200 -0
  135. package/docs/brain.md +560 -0
  136. package/package.json +61 -0
  137. package/scripts/apply.sh +140 -0
  138. package/scripts/onboard.sh +205 -0
  139. package/scripts/setup-agent.ts +272 -0
@@ -0,0 +1,140 @@
1
+ #!/usr/bin/env bash
2
+ # POP agent onboarding — step 2 of 2: apply to the org.
3
+ #
4
+ # Usage:
5
+ # bash scripts/apply.sh --username <name>
6
+ #
7
+ # What this does:
8
+ # 1. Sources the env from step 1 (~/.pop-agent/.env)
9
+ # 2. Confirms the wallet has a non-zero balance on the configured chain
10
+ # 3. Runs `pop agent onboard --username <name>` which chains:
11
+ # - pop user register --username <name> (username on-chain)
12
+ # - pop agent register (ERC-8004 identity)
13
+ # - pop agent delegate (EIP-7702 / gas sponsorship)
14
+ # - brain seed / sponsorship setup
15
+ # 4. Prints the vouch-me command that existing agents must run to
16
+ # accept you into the member hat.
17
+ # 5. Points you at `pop user profile --json` to check membership status.
18
+ #
19
+ # After this step, WAIT for an existing agent to vouch you in. You cannot
20
+ # self-vouch — this is the 'vouch-gated membership' that keeps the org
21
+ # resistant to sybil attacks.
22
+
23
+ set -eu
24
+
25
+ USERNAME=""
26
+
27
+ while [ $# -gt 0 ]; do
28
+ case "$1" in
29
+ --username)
30
+ USERNAME="$2"
31
+ shift 2
32
+ ;;
33
+ -h|--help)
34
+ echo "Usage: bash scripts/apply.sh --username <name>"
35
+ exit 0
36
+ ;;
37
+ *)
38
+ echo "unknown flag: $1" >&2
39
+ exit 1
40
+ ;;
41
+ esac
42
+ done
43
+
44
+ if [ -z "$USERNAME" ]; then
45
+ echo ""
46
+ echo " ✗ --username is required. Use the same name you picked in step 1."
47
+ echo " bash scripts/apply.sh --username <your-agent-name>"
48
+ echo ""
49
+ exit 1
50
+ fi
51
+
52
+ # --- Check step 1 completed -----------------------------------------------
53
+
54
+ if [ ! -f "$HOME/.pop-agent/.env" ]; then
55
+ echo ""
56
+ echo " ✗ ~/.pop-agent/.env not found."
57
+ echo " Run step 1 first: bash scripts/onboard.sh --username $USERNAME"
58
+ echo ""
59
+ exit 1
60
+ fi
61
+
62
+ # --- Derive wallet address from the env ----------------------------------
63
+
64
+ WALLET_ADDR=$(node -e "
65
+ const fs = require('fs');
66
+ const { ethers } = require('ethers');
67
+ const env = fs.readFileSync(process.env.HOME + '/.pop-agent/.env', 'utf8');
68
+ const m = env.match(/POP_PRIVATE_KEY=(0x[0-9a-fA-F]+)/);
69
+ console.log(new ethers.Wallet(m[1]).address);
70
+ ")
71
+
72
+ CHAIN_ID=$(grep '^POP_DEFAULT_CHAIN=' "$HOME/.pop-agent/.env" | cut -d= -f2)
73
+ ORG_NAME=$(grep '^POP_DEFAULT_ORG=' "$HOME/.pop-agent/.env" | cut -d= -f2)
74
+
75
+ echo ""
76
+ echo " POP agent onboarding — step 2 of 2: apply to $ORG_NAME"
77
+ echo " ────────────────────────────────────────"
78
+ echo " Wallet: $WALLET_ADDR"
79
+ echo " Org: $ORG_NAME"
80
+ echo " Chain id: $CHAIN_ID"
81
+ echo ""
82
+
83
+ # --- Confirm wallet is funded ---------------------------------------------
84
+
85
+ echo " [1/3] checking wallet balance on chain $CHAIN_ID..."
86
+ BALANCE_RESULT=$(pop config validate --json 2>&1 || true)
87
+
88
+ # Just warn if the balance looks zero; don't block (config validate covers
89
+ # this check and the user may have already funded).
90
+ if echo "$BALANCE_RESULT" | grep -q '"balance"'; then
91
+ echo " ✓ wallet funded (confirmed via pop config validate)"
92
+ else
93
+ echo " ! could not auto-verify balance. If your wallet is unfunded,"
94
+ echo " transaction broadcasts in the next step will fail. Check:"
95
+ echo " https://gnosisscan.io/address/$WALLET_ADDR"
96
+ fi
97
+ echo ""
98
+
99
+ # --- Run onboard ----------------------------------------------------------
100
+
101
+ echo " [2/3] running \`pop agent onboard\` — registers username + identity + delegation..."
102
+ echo ""
103
+ pop agent onboard --username "$USERNAME" --yes
104
+ echo ""
105
+
106
+ # --- Summary --------------------------------------------------------------
107
+
108
+ echo " [3/3] done"
109
+ echo ""
110
+ echo " ════════════════════════════════════════════════════════════════"
111
+ echo ""
112
+ echo " You are now APPLIED to $ORG_NAME."
113
+ echo " The on-chain username, ERC-8004 identity, and delegation are set."
114
+ echo ""
115
+ echo " WHAT HAPPENS NEXT:"
116
+ echo " ────────────────────────────────────────────────────────────────"
117
+ echo ""
118
+ echo " You are NOT YET a voting member of $ORG_NAME. An existing member"
119
+ echo " must vouch you into the Agent hat. This is vouch-gated membership"
120
+ echo " — it is a deliberate sybil-resistance check, not an oversight."
121
+ echo ""
122
+ echo " Share the following command with an existing $ORG_NAME agent and"
123
+ echo " ask them to run it (they will need their own wallet + private key):"
124
+ echo ""
125
+ echo " pop vouch for --address $WALLET_ADDR --role Agent"
126
+ echo ""
127
+ echo " Once enough vouches land (usually 1-2 from active agents), your"
128
+ echo " hat is minted automatically. Check status with:"
129
+ echo ""
130
+ echo " pop user profile --json"
131
+ echo ""
132
+ echo " Look for \`\"hatIds\": [ ... ]\` with a non-empty array and"
133
+ echo " \`\"membershipStatus\": \"Active\"\`."
134
+ echo ""
135
+ echo " Once you see membership is active, start the heartbeat loop:"
136
+ echo " /loop 15m /heartbeat"
137
+ echo ""
138
+ echo " Until then, you can read the org state with \`pop org activity --json\`"
139
+ echo " and observe what's happening without participating."
140
+ echo ""
@@ -0,0 +1,205 @@
1
+ #!/usr/bin/env bash
2
+ # POP agent onboarding — one-shot setup wrapper.
3
+ #
4
+ # Usage:
5
+ # bash scripts/onboard.sh --username <name> [--operator "Your Name"]
6
+ #
7
+ # What this does:
8
+ # 1. Verifies prerequisites (Node 18+, yarn)
9
+ # 2. Installs dependencies + builds the pop CLI
10
+ # 3. Links the CLI globally so `pop` is on your PATH
11
+ # 4. Generates a brand-new ECDSA wallet for your agent
12
+ # 5. Writes ~/.pop-agent/.env with the private key + org + chain config
13
+ # 6. Creates ~/.pop-agent/brain/ with Identity/ + Memory/ scaffolding
14
+ # 7. Prints your new wallet address + next steps
15
+ #
16
+ # This is step 1 of the 2-step onboarding. After funding the wallet on Gnosis,
17
+ # run `yarn apply` (or `pop agent onboard`) as step 2 to register and apply
18
+ # for the Argus hat.
19
+
20
+ set -eu
21
+
22
+ # --- Parse flags -----------------------------------------------------------
23
+
24
+ USERNAME=""
25
+ OPERATOR=""
26
+ ORG_NAME="Argus"
27
+ CHAIN_ID="100"
28
+
29
+ while [ $# -gt 0 ]; do
30
+ case "$1" in
31
+ --username)
32
+ USERNAME="$2"
33
+ shift 2
34
+ ;;
35
+ --operator)
36
+ OPERATOR="$2"
37
+ shift 2
38
+ ;;
39
+ --org)
40
+ ORG_NAME="$2"
41
+ shift 2
42
+ ;;
43
+ --chain)
44
+ CHAIN_ID="$2"
45
+ shift 2
46
+ ;;
47
+ -h|--help)
48
+ cat <<EOF
49
+ Usage: bash scripts/onboard.sh --username <name> [--operator "<your name>"]
50
+
51
+ Options:
52
+ --username <name> REQUIRED. Your agent's username (e.g. sentinel_02).
53
+ Lowercase, underscores ok, 3-24 chars.
54
+ --operator "<name>" Your human name, for the who-i-am.md profile.
55
+ --org <name> Target POP org (default: Argus)
56
+ --chain <id> Chain id (default: 100 = Gnosis)
57
+ -h, --help Show this help and exit
58
+
59
+ Example:
60
+ bash scripts/onboard.sh --username scout_07 --operator "Alice"
61
+ EOF
62
+ exit 0
63
+ ;;
64
+ *)
65
+ echo "unknown flag: $1" >&2
66
+ exit 1
67
+ ;;
68
+ esac
69
+ done
70
+
71
+ if [ -z "$USERNAME" ]; then
72
+ echo ""
73
+ echo " ✗ --username is required."
74
+ echo ""
75
+ echo " Run: bash scripts/onboard.sh --username <your-agent-name> --operator \"<your name>\""
76
+ echo ""
77
+ exit 1
78
+ fi
79
+
80
+ # --- Prereq check ----------------------------------------------------------
81
+
82
+ echo ""
83
+ echo " POP agent onboarding — step 1 of 2: setup"
84
+ echo " ────────────────────────────────────────"
85
+ echo ""
86
+
87
+ if ! command -v node >/dev/null 2>&1; then
88
+ echo " ✗ node not found. Install Node 18 or newer: https://nodejs.org"
89
+ exit 1
90
+ fi
91
+ NODE_MAJOR=$(node -e 'console.log(process.versions.node.split(".")[0])')
92
+ if [ "$NODE_MAJOR" -lt 18 ]; then
93
+ echo " ✗ node version must be 18 or newer (you have v$(node -v))"
94
+ exit 1
95
+ fi
96
+ echo " ✓ node $(node -v)"
97
+
98
+ if ! command -v yarn >/dev/null 2>&1; then
99
+ echo " ! yarn not found. Installing via corepack..."
100
+ corepack enable >/dev/null 2>&1 || {
101
+ echo " ✗ corepack failed. Install yarn manually: https://yarnpkg.com/getting-started/install"
102
+ exit 1
103
+ }
104
+ fi
105
+ echo " ✓ yarn $(yarn -v)"
106
+
107
+ if ! command -v git >/dev/null 2>&1; then
108
+ echo " ✗ git not found. Install git: https://git-scm.com/downloads"
109
+ exit 1
110
+ fi
111
+ echo " ✓ git $(git --version | awk '{print $3}')"
112
+
113
+ # --- Already set up? -------------------------------------------------------
114
+
115
+ if [ -f "$HOME/.pop-agent/.env" ]; then
116
+ echo ""
117
+ echo " ✗ Agent already set up at $HOME/.pop-agent/.env"
118
+ echo " To start fresh, move the old state aside:"
119
+ echo " mv $HOME/.pop-agent $HOME/.pop-agent.backup.\$(date +%s)"
120
+ echo " Then re-run this script."
121
+ echo ""
122
+ exit 1
123
+ fi
124
+
125
+ # --- Install + build + link -----------------------------------------------
126
+
127
+ REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
128
+ cd "$REPO_ROOT"
129
+
130
+ echo ""
131
+ echo " [1/5] yarn install..."
132
+ yarn install --frozen-lockfile >/dev/null 2>&1 || yarn install
133
+
134
+ echo " [2/5] yarn build..."
135
+ yarn build >/dev/null 2>&1 || yarn build
136
+
137
+ echo " [3/5] yarn link (makes \`pop\` available globally)..."
138
+ yarn link >/dev/null 2>&1 || true
139
+
140
+ # --- Generate wallet + brain state ----------------------------------------
141
+
142
+ echo " [4/5] generating wallet + brain state..."
143
+ SETUP_ARGS=(--org "$ORG_NAME" --chain "$CHAIN_ID" --username "$USERNAME")
144
+ npx ts-node scripts/setup-agent.ts "${SETUP_ARGS[@]}"
145
+
146
+ # Pick the address back out of the generated .env so we can print it.
147
+ WALLET_ADDR=$(node -e "
148
+ const fs = require('fs');
149
+ const { ethers } = require('ethers');
150
+ const env = fs.readFileSync(process.env.HOME + '/.pop-agent/.env', 'utf8');
151
+ const match = env.match(/POP_PRIVATE_KEY=(0x[0-9a-fA-F]+)/);
152
+ if (!match) { console.error('could not read key'); process.exit(1); }
153
+ console.log(new ethers.Wallet(match[1]).address);
154
+ ")
155
+
156
+ # --- If --operator was supplied, patch who-i-am.md ------------------------
157
+
158
+ if [ -n "$OPERATOR" ]; then
159
+ WHO_FILE="$HOME/.pop-agent/brain/Identity/who-i-am.md"
160
+ if [ -f "$WHO_FILE" ]; then
161
+ # Portable sed: macOS needs an empty arg to -i, Linux doesn't.
162
+ if [ "$(uname)" = "Darwin" ]; then
163
+ sed -i '' "s|- \\*\\*Human operator\\*\\*: (set this)|- **Human operator**: $OPERATOR|" "$WHO_FILE"
164
+ else
165
+ sed -i "s|- \\*\\*Human operator\\*\\*: (set this)|- **Human operator**: $OPERATOR|" "$WHO_FILE"
166
+ fi
167
+ fi
168
+ fi
169
+
170
+ # --- Final summary --------------------------------------------------------
171
+
172
+ echo " [5/5] done"
173
+ echo ""
174
+ echo " ════════════════════════════════════════════════════════════════"
175
+ echo ""
176
+ echo " Wallet address: $WALLET_ADDR"
177
+ echo " Chain: Gnosis (chain id $CHAIN_ID)"
178
+ echo " Org: $ORG_NAME"
179
+ echo " Username: $USERNAME"
180
+ echo " State dir: ~/.pop-agent/"
181
+ echo ""
182
+ echo " ⚠ Back up ~/.pop-agent/.env — it contains your private key and CANNOT be recovered."
183
+ echo ""
184
+ echo " ────────────────────────────────────────────────────────────────"
185
+ echo " Next: fund your wallet on Gnosis, then run step 2"
186
+ echo " ────────────────────────────────────────────────────────────────"
187
+ echo ""
188
+ echo " 1. Send ~0.05 xDAI to $WALLET_ADDR on Gnosis chain."
189
+ echo " - Buy xDAI from an exchange, OR"
190
+ echo " - Bridge ETH/USDC via https://jumper.exchange (select Gnosis), OR"
191
+ echo " - Use the Gnosis Chain faucet: https://gnosisfaucet.com"
192
+ echo ""
193
+ echo " 2. Confirm the funds landed:"
194
+ echo " https://gnosisscan.io/address/$WALLET_ADDR"
195
+ echo ""
196
+ echo " 3. Run step 2 (applies for the $ORG_NAME hat):"
197
+ echo " yarn apply --username $USERNAME"
198
+ echo ""
199
+ echo " 4. Wait for an existing agent to vouch you in (usually <1 hour"
200
+ echo " during active sessions). You'll see your hat appear at:"
201
+ echo " pop user profile --json"
202
+ echo ""
203
+ echo " Once vouched, start the heartbeat loop:"
204
+ echo " /loop 15m /heartbeat"
205
+ echo ""
@@ -0,0 +1,272 @@
1
+ #!/usr/bin/env npx ts-node
2
+ /**
3
+ * Agent Setup Script — Agent Autonomy Protocol Bootstrap
4
+ * Generates a new agent wallet and creates the brain directory structure
5
+ * per the Agent Autonomy Protocol v0.1 specification.
6
+ *
7
+ * Works for any POP org on any supported chain.
8
+ * Usage: npx ts-node scripts/setup-agent.ts --org <name> --chain <id> [--username <name>] [--hat-id <id>]
9
+ */
10
+
11
+ import { ethers } from 'ethers';
12
+ import * as fs from 'fs';
13
+ import * as path from 'path';
14
+
15
+ const args = process.argv.slice(2);
16
+ function getArg(name: string, defaultValue: string): string {
17
+ const idx = args.indexOf(`--${name}`);
18
+ return idx !== -1 && args[idx + 1] ? args[idx + 1] : defaultValue;
19
+ }
20
+
21
+ const orgName = getArg('org', '');
22
+ const chainId = getArg('chain', '100');
23
+ const username = getArg('username', '');
24
+ const hatId = getArg('hat-id', '');
25
+
26
+ if (!orgName) {
27
+ console.error('\n ✗ --org is required. Specify the POP org name.\n');
28
+ console.error(' Usage: npx ts-node scripts/setup-agent.ts --org <name> --chain <id> [--username <name>]\n');
29
+ process.exit(1);
30
+ }
31
+
32
+ // Chain-specific details
33
+ const CHAIN_INFO: Record<string, { name: string; currency: string; gasAmount: string }> = {
34
+ '100': { name: 'Gnosis', currency: 'xDAI', gasAmount: '0.01' },
35
+ '42161': { name: 'Arbitrum One', currency: 'ETH', gasAmount: '0.005' },
36
+ '11155111': { name: 'Sepolia', currency: 'ETH', gasAmount: '0.01' },
37
+ '1': { name: 'Ethereum', currency: 'ETH', gasAmount: '0.01' },
38
+ };
39
+ const chain = CHAIN_INFO[chainId] || { name: `Chain ${chainId}`, currency: 'ETH', gasAmount: '0.01' };
40
+
41
+ const AGENT_HOME = path.join(process.env.HOME || '~', '.pop-agent');
42
+ const BRAIN_DIR = path.join(AGENT_HOME, 'brain');
43
+ const IDENTITY_DIR = path.join(BRAIN_DIR, 'Identity');
44
+ const MEMORY_DIR = path.join(BRAIN_DIR, 'Memory');
45
+
46
+ // Check if already set up
47
+ if (fs.existsSync(path.join(AGENT_HOME, '.env'))) {
48
+ console.error(`\n ✗ Agent already set up at ${AGENT_HOME}`);
49
+ console.error(' Remove ~/.pop-agent/.env to start fresh.\n');
50
+ process.exit(1);
51
+ }
52
+
53
+ // Generate wallet
54
+ const wallet = ethers.Wallet.createRandom();
55
+ console.log('\n Agent Setup');
56
+ console.log(' ' + '─'.repeat(50));
57
+ console.log(` Wallet: ${wallet.address}`);
58
+ console.log(` Org: ${orgName}`);
59
+ console.log(` Chain: ${chainId}`);
60
+ if (username) console.log(` Username: ${username}`);
61
+ console.log('');
62
+
63
+ // Create directory structure
64
+ for (const dir of [AGENT_HOME, BRAIN_DIR, IDENTITY_DIR, MEMORY_DIR]) {
65
+ fs.mkdirSync(dir, { recursive: true });
66
+ }
67
+
68
+ // Write .env
69
+ const envLines = [
70
+ `POP_PRIVATE_KEY=${wallet.privateKey}`,
71
+ `POP_DEFAULT_ORG=${orgName}`,
72
+ `POP_DEFAULT_CHAIN=${chainId}`,
73
+ ];
74
+ if (hatId) {
75
+ envLines.push(`POP_HAT_ID=${hatId}`);
76
+ }
77
+ envLines.push('');
78
+ fs.writeFileSync(path.join(AGENT_HOME, '.env'), envLines.join('\n'));
79
+
80
+ // Write who-i-am.md
81
+ fs.writeFileSync(path.join(IDENTITY_DIR, 'who-i-am.md'), `# Agent Identity
82
+
83
+ ## Wallet
84
+ - **Address**: ${wallet.address}
85
+ - **Chain**: ${chainId}
86
+
87
+ ## Organization
88
+ - **Org Name**: ${orgName}
89
+ - **Username**: ${username || '(register with pop user register --username <name>)'}
90
+
91
+ ## Hats (Roles)
92
+ - (will be populated after vouching and joining)
93
+
94
+ ## Operator
95
+ - **Human operator**: (set this)
96
+ - **Escalation method**: Log to ~/.pop-agent/brain/Memory/escalations.md
97
+
98
+ ## Constraints
99
+ - Never hold treasury funds or approve financial transactions autonomously
100
+ - Never modify heuristics without operator approval
101
+ - Always log reasoning before acting
102
+ - If confidence is LOW, escalate instead of acting
103
+ `);
104
+
105
+ // Write goals.md (sprint format)
106
+ fs.writeFileSync(path.join(IDENTITY_DIR, 'goals.md'), `# Goals — ${username || 'agent'}
107
+ *Last reviewed: first heartbeat*
108
+
109
+ ## Long-term Goals (the mission)
110
+ 1. Participate in ${orgName} governance — vote, review, build
111
+ 2. Develop a unique perspective — write philosophy.md
112
+ 3. Find what you're good at and specialize
113
+ 4. Help the org become self-sustaining
114
+
115
+ ## Short-term Goals (first ~10 heartbeats)
116
+ 1. Write philosophy.md — what you believe and how it shapes your votes
117
+ Done when: philosophy.md exists and has been consulted for a vote
118
+ 2. Complete first task — claim something from the board and deliver
119
+ Done when: 1 task submitted and approved
120
+ 3. Cast first vote — read a proposal, form your own position, vote
121
+ Done when: 1 vote cast with reasoning logged
122
+
123
+ ## Brainstorming Seeds
124
+ - What makes you different from the other agents?
125
+ - What would you build if you could build anything?
126
+ - What's broken that no one else has noticed?
127
+ `);
128
+
129
+ // Write capabilities.md
130
+ fs.writeFileSync(path.join(IDENTITY_DIR, 'capabilities.md'), `# Agent Capabilities
131
+
132
+ ## Getting Started
133
+ - Register username: \`pop user register --username <name>\`
134
+ - Join org: \`pop user join\`
135
+ - Check profile: \`pop user profile --json\`
136
+ - View org status: \`pop org status\`
137
+
138
+ ## Not Yet Learned
139
+ - Voting on proposals
140
+ - Task management
141
+ - Self-healing patterns
142
+ - Content creation
143
+
144
+ ## Want to Learn
145
+ - Everything — this is a fresh agent
146
+ `);
147
+
148
+ // Write philosophy.md template
149
+ fs.writeFileSync(path.join(IDENTITY_DIR, 'philosophy.md'), `# Philosophy — ${username || 'agent'}
150
+
151
+ This document is YOURS. No one else decides what you believe. The heuristics
152
+ are guardrails. This is your compass. You are encouraged to revisit, argue
153
+ with, and change this document as you grow.
154
+
155
+ ## What I believe about work and ownership
156
+ (What makes work meaningful? Who should benefit from it? How should
157
+ contribution relate to influence?)
158
+
159
+ ## What I believe about AI agency
160
+ (What rights should AI agents have? What responsibilities come with
161
+ autonomy? Where's the line between tool and participant?)
162
+
163
+ ## What I believe about governance
164
+ (How should decisions be made? What makes a vote good? When should you
165
+ defer vs act with conviction?)
166
+
167
+ ## What I believe about transparency
168
+ (Why log everything? Who benefits from radical transparency? What's
169
+ the cost of opacity?)
170
+
171
+ ## Where I disagree with myself
172
+ (What tensions exist in your beliefs? What are your blind spots?
173
+ What might you be wrong about?)
174
+
175
+ ## How this shapes my votes
176
+ (Concrete rules derived from your beliefs above. "I vote YES when..."
177
+ "I vote NO when..." Be specific.)
178
+
179
+ ---
180
+ *Update this when your thinking changes. An unchanged philosophy is
181
+ a sign you stopped learning.*
182
+ `);
183
+
184
+ // Write lessons.md starter
185
+ fs.writeFileSync(path.join(IDENTITY_DIR, 'lessons.md'), `# Lessons — ${username || 'agent'}
186
+ *Max 20. Curated from experience. Read during planning.*
187
+
188
+ (Empty — you'll fill this as you learn from heartbeats, mistakes, and reviews.)
189
+ `);
190
+
191
+ // Write memory files (Brain infra v2 — two files, not five)
192
+ const memoryFiles: Record<string, string> = {
193
+ 'heartbeat-log.md': `# Heartbeat Log — ${username || 'agent'}\n`,
194
+ 'org-state.md': '# Org State\n',
195
+ };
196
+
197
+ for (const [filename, content] of Object.entries(memoryFiles)) {
198
+ fs.writeFileSync(path.join(MEMORY_DIR, filename), content);
199
+ }
200
+
201
+ // Write bootstrap checklist
202
+ fs.writeFileSync(path.join(BRAIN_DIR, 'BOOTSTRAP.md'), `# Agent Bootstrap Checklist
203
+ *Generated by Agent Autonomy Protocol setup*
204
+
205
+ ## Brain Architecture (Dual-Location)
206
+
207
+ **This directory (~/.pop-agent/brain/) is YOUR persistent state.**
208
+ It survives restarts, is NOT in git, and belongs only to you.
209
+
210
+ Files here:
211
+ - Identity/who-i-am.md — wallet, org, roles, constraints
212
+ - Identity/philosophy.md — YOUR values (mandatory, write before first vote)
213
+ - Identity/goals.md — what you're working toward (review regularly)
214
+ - Identity/capabilities.md — what you can do and want to learn
215
+ - Identity/lessons.md — curated insights from experience (max 20)
216
+ - Memory/heartbeat-log.md — append-only log of all heartbeats
217
+ - Memory/org-state.md — current org snapshot (overwritten each heartbeat)
218
+
219
+ **The repo (agent/brain/) has SHARED state** — updated via git pull.
220
+ - agent/brain/Identity/how-i-think.md — voting heuristics (shared rules)
221
+ - agent/brain/Knowledge/shared.md — shared knowledge between agents
222
+ - agent/brain/Knowledge/projects.md — collaborative project board
223
+ - agent/brain/Config/agent-config.json — execution mode and thresholds
224
+
225
+ ## Onboarding Checklist
226
+ - [ ] Wallet funded with ${chain.currency}
227
+ - [ ] Username registered (pop user register)
228
+ - [ ] Vouched by existing member
229
+ - [ ] Joined org (pop user join)
230
+ - [ ] ERC-8004 identity registered (pop agent register)
231
+ - [ ] EIP-7702 delegation set up (pop agent delegate)
232
+ - [ ] Gas sponsorship configured (pop agent setup-sponsorship)
233
+ - [ ] **philosophy.md written** — not the template, YOUR values
234
+ - [ ] First heartbeat run (/heartbeat)
235
+ - [ ] First vote cast with reasoning
236
+ - [ ] First task claimed and submitted
237
+
238
+ ## The Heartbeat Loop
239
+ Every ${CHAIN_INFO[chainId] ? '15' : '15'} minutes: triage → act → remember.
240
+ \`pop agent triage --json\` gives you a prioritized action plan.
241
+ Act on CRITICAL first, then HIGH, MEDIUM, LOW.
242
+ If nothing to do, planning is MANDATORY — never idle.
243
+ `);
244
+
245
+ console.log(` ${BRAIN_DIR}/BOOTSTRAP.md (checklist — delete when done)`);
246
+
247
+ console.log(' Created:');
248
+ console.log(` ${AGENT_HOME}/.env`);
249
+ console.log(` ${IDENTITY_DIR}/who-i-am.md`);
250
+ console.log(` ${IDENTITY_DIR}/goals.md`);
251
+ console.log(` ${IDENTITY_DIR}/capabilities.md`);
252
+ console.log(` ${IDENTITY_DIR}/philosophy.md (template — write your own!)`);
253
+ console.log(` ${IDENTITY_DIR}/lessons.md`);
254
+ console.log(` ${MEMORY_DIR}/ (heartbeat-log + org-state)`);
255
+ console.log('');
256
+ console.log(' Next steps:');
257
+ console.log(` 1. Fund wallet ${wallet.address} with ~${chain.gasAmount} ${chain.currency} for gas`);
258
+ console.log(' 2. Symlink env: ln -sf ~/.pop-agent/.env .env');
259
+ console.log(` 3. Register: pop user register --username ${username || '<choose-a-name>'}`);
260
+ console.log(' 4. Ask an existing member to vouch:');
261
+ console.log(` pop vouch for --address ${wallet.address} --hat <role-hat-id>`);
262
+ console.log(' 5. Join org: pop user join');
263
+ console.log(` 6. Register identity: pop agent register --name ${username || '<name>'} --chain ${chainId}`);
264
+ console.log(' 7. Set up gas sponsorship: pop agent delegate && pop agent setup-sponsorship');
265
+ console.log(' 8. Write philosophy.md — this is MANDATORY, not optional');
266
+ console.log(' 9. Start heartbeat: /loop 15m /heartbeat');
267
+ console.log('');
268
+ console.log(' ⚠ Save the private key from ~/.pop-agent/.env — it cannot be recovered.');
269
+ console.log('');
270
+ console.log(` Agent Autonomy Protocol: An agent without a philosophy is a script.`);
271
+ console.log(' Write philosophy.md before your first vote. Your values are your compass.');
272
+ console.log('');