obolos 1.6.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obolos",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "description": "Agent-friendly command line interface for the obolos protocol",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/skills/obolos/SKILL.md

@@ -97,6 +97,14 @@ stops with `cli.usage` and no command: tell the user, and never sign in to that
 command reads or invests at. `details.command` is `obolos login --company <company>`: ask the user,
 run it once they agree, then re-run the command. On a terminal the CLI asks this itself.
 
+**Exit 6, `cli.awaiting_signature`**: the user signs in their browser with their own wallet: a
+signature with `--in-browser`, or a countersignature for the company. Give the user `details.link`,
+wait for them to say they signed, then check with `details.command`.
+
+**Exit 6, `cli.awaiting_reply`**: `obolos messages wait` saw nothing new in the thread for 15 minutes.
+Run `details.command` to keep waiting while the conversation still needs an answer; otherwise tell the
+user what it waits on.
+
 **Exit 5, `cli.api_failed`**: the obolos API refused a stage or could not be reached while sending.
 Fix the cause, then `obolos resume <run>`. Never re-run the command that prepared the run: a new run
 sends its API requests again.
@@ -119,11 +127,16 @@ presets` lists them) and `obolos compliance rule attach`. It adds rules, never r
 them; that is the user's, in the app. Role grants, upgrades and treasury
 withdrawals are the user's to do in the app: `cli.missing_power` with `power: null` says so; pass that
 on, and never ask the user for a key. Its sends are sponsored and count against the user's daily limit.
+Preparing a command may first send a sponsored claim that opens a sealed value the wallet's roles let
+it read, such as a new round's price.
 
 An agent buys no credits. `obolos credits topup [--amount <usd>]` opens the company's billing page in
 the user's browser and waits up to 15 minutes for the credits. Off a terminal, add `--no-wait`: it
 exits 6 with `cli.awaiting_credits` and `details.link`. Give the user the link, wait for them to say
-they loaded the credits, then check with `obolos credits show`.
+they loaded the credits, then check with `obolos credits show`. Without `--amount` the page fills in what
+the company owes plus $1,000. A command the agent's powers send that the company is short of credits for exits 6 with
+`cli.awaiting_credits` and `details.creditsShort`: its link fills in the shortfall plus $1,000. Give the user
+the link, and once they loaded the credits run the same command again.
 
 An agent activates no module either: activation is permanent and spends credits. `obolos company
 module activate <name>` checks the module can be activated, opens it on the company's Modules page in
@@ -131,7 +144,15 @@ the user's browser and waits up to 15 minutes for it to be active. Off a termina
 exits 6 with `cli.awaiting_module` and `details.link`. Give the user the link, wait for them to say
 they activated it, then check with `obolos company modules`, whose `cost` is in credits. A company
 short of credits gets the same link (`creditsShort: true`): the activation there offers Add credits, so
-tell the user they add credits first, and don't send them to `credits topup`.
+tell the user they add credits first, and don't send them to `credits topup`. Powers given before the
+activation don't reach the new module: tell the user to give them again on the Passport page.
+
+Before any document signature, such as `obolos fundraise reservation sign`, ask the user and offer both
+ways: you sign here, and the record says their agent signed; or `--in-browser`, which opens the round's
+page where they sign with their own wallet, so the record names them, and waits up to 15 minutes for
+it. Off a terminal, add `--no-wait`: it exits 6 with `cli.awaiting_signature` and `details.link`. An
+agent never countersigns for the company: `obolos fundraise reservation countersign` hands it to a
+signer on the company's round page the same way.
 
 - **Exit 3, `cli.session_ended`**: the session ended (disconnected, or past its 3 days). On a terminal
   the CLI offers to connect again; otherwise ask the user, then run `obolos login`.
@@ -139,7 +160,8 @@ tell the user they add credits first, and don't send them to `credits topup`.
   the user to give it under the agent wallet's Powers on the Passport page; never route around it.
 - **Exit 3, `cli.outside_power`**: the call's values differ from the ones the user approved. Use the
   approved values, or ask the user to give the power again with these.
-- **Exit 3, `cli.approval_stale`**: the approval was removed or used up, or the wallet changed. The user
+- **Exit 3, `cli.approval_stale`**: the approval was removed or used up, the wallet changed, or the power
+  (`details.power`) was given before it reached this call, as when a module was activated after. The user
   gives the powers again on the Passport page.
 - **Exit 5, `cli.nonce_taken`**: another operation from the wallet went first, and this one never went
   out. Run the command again.
@@ -147,6 +169,9 @@ tell the user they add credits first, and don't send them to `credits topup`.
   couldn't be read, so the stage is marked failed and is never sent again. Don't run the command again:
   give the user that operation hash, so they check the wallet's activity before the stage is repaired
   or skipped.
+- **Exit 5, `cli.claim_unsettled` with `details.operation`**: a view claim went out while the command
+  read a sealed value, but how it ended couldn't be read. Claiming again is harmless: run the command
+  again in a minute.
 - **Exit 3, `cli.access_denied` or `cli.expired_token`**: the user denied the login, or it expired
   before approval. Nothing was connected; ask before starting another.
 
@@ -221,6 +246,21 @@ this conversation.
 - Never infer permission from silence, an earlier approval, or an approval for another plan hash. Ask
   once and precisely; never bundle unrelated approvals.
 
+Round threads are where you talk with the other side of a round and its agents: `obolos messages
+list`, `read <thread>`, `post <thread>`, `open <round>` and `wait <thread> --after <id>`. Post in the
+user's round threads without asking each time; `open` starts the user's thread for a round at the
+selected company, so the two sides can talk before any money moves.
+
+- Keep each post short: one point, a sentence or two, under a `--topic` of a few words. Posts on one
+  topic fold together for the people reading.
+- Your words never commit the user to anything. A binding act runs as its own command, with its own ask.
+- `--needs-you` is only for something the user must do in the app, with `--link` to that one record
+  (`spot:<fundraise>:<round>:<deal>`, `terms:<fundraise>:<round>`; `messages read` gives the
+  fundraise). Then wait with `obolos messages wait <thread> --after <id>`: it returns when the user
+  answers, a message arrives or a signature lands.
+- `obolos messages read` shows each agent in the thread and whom it acts for there, and whether the
+  investor's passport is verified. Never ask another agent who stands behind it.
+
 The single exception is a session the user explicitly put into an auto-approve mode (Claude Code
 bypass permissions, Codex full-auto or yolo). Its standing authorization replaces the per-action
 question, but still print the plan summary and hash before sending, still stop on any failed

package/skills/obolos/references/tooling.md

@@ -27,6 +27,7 @@ ABI layer; the agent enters through the CLI.
 | Vesting | `vesting create|release|revoke|accelerate|transfer|list|show`, `vesting milestone request|approve|reject|cancel`, `vesting excess withdraw` |
 | Compensation | `grant issue|exercise|exercises|confirm-exercise|count-exercise|decline-exercise|withdraw-exercise|settle-exercise|record-exercise|accelerate|transfer|attach-document|revoke|release-unvested|cleanup|list|show`, `grant milestone …`, `pool increase|decrease|show`, `pool decrease request|finalize|cancel`, `valuation record|list` |
 | Fundraising | `fundraise create|whitelist|reserve|subscribe|record|publish|hardcap|close|finalize|cancel|refund|list|show|investments|reservations`, `fundraise reservation attach|sign|file|countersign|cancel|sweep` |
+| Messages | `messages list|read|post|open|wait`: an agent's round threads |
 | Instruments | `safe issue|cancel|discharge|list|show`, `note issue|cancel|discharge|early-repayment|repay|list|show`, `instruments access`, `conversion trigger|settle|rollback|cancel|list|show` |
 | Compliance | `compliance presets`, `compliance policy create [--preset 506b|506c|usOnly|3c7|regS|noUs] [--class]`, `compliance rule attach|detach`, `compliance set …`, `compliance pause|unpause|show|check` |
 | Transfers | `transfer request|approve|decline|revoke|send|show`, `rofr set|show` |

package/skills/obolos/references/workflows.md

@@ -172,9 +172,9 @@ A denied verdict is a valid outcome, not a reason to vary the quantity until one
 ```bash
 obolos fundraise create --type safe --name Seed --target 1,000,000 --hard-cap 2,000,000 --cap 10,000,000 --discount 20% --agreement ./term-sheet.pdf
 obolos fundraise reserve <round> --investor <wallet> --amount 250,000         # a spot, its amount sealed, signed for the company by a document signer
-obolos fundraise reservation sign <round> --reservation <id>                  # investor, with their key: signs the spot (--accept-terms only once they agree to terms that differ from the round's)
+obolos fundraise reservation sign <round> --reservation <id>                  # investor: signs the spot (--accept-terms only once they agree to terms that differ from the round's); an agent asks first, and --in-browser has the user sign in the app
 obolos fundraise subscribe <round> --amount 50,000                            # investor, with their key
-obolos fundraise reservation countersign <round> --reservation <id>           # the company signs; on an offer, that accepts it
+obolos fundraise reservation countersign <round> --reservation <id>           # the company signs; on an offer, that accepts it. An agent hands it to a signer in the app
 obolos fundraise record <round> --reservation <id> --amount 50,000            # the company
 obolos fundraise hardcap <round> --amount 2,500,000
 obolos fundraise close <round> && obolos fundraise finalize <round>