@kodelyth/tlon 2026.5.39 → 2026.5.42
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 +5 -0
- package/api.ts +16 -0
- package/channel-plugin-api.ts +1 -0
- package/dist/api.js +4 -0
- package/dist/channel-Bvzym9ez.js +236 -0
- package/dist/channel-plugin-api.js +2 -0
- package/dist/channel.runtime-CDY2BdfM.js +3626 -0
- package/dist/doctor-contract-Ip6FcHDH.js +7 -0
- package/dist/doctor-contract-api.js +2 -0
- package/dist/index.js +18 -0
- package/dist/runtime-BmSb9A-q.js +8 -0
- package/dist/runtime-api-Dq8wkBC_.js +4 -0
- package/dist/runtime-api.js +2 -0
- package/dist/setup-api.js +3 -0
- package/dist/setup-core-CF3ryHqs.js +387 -0
- package/dist/setup-entry.js +11 -0
- package/dist/setup-surface-BM5_V_XL.js +74 -0
- package/dist/test-api.js +2 -0
- package/doctor-contract-api.ts +1 -0
- package/index.ts +16 -0
- package/klaw.plugin.json +3 -203
- package/package.json +4 -4
- package/runtime-api.ts +17 -0
- package/setup-api.ts +2 -0
- package/setup-entry.ts +9 -0
- package/src/account-fields.ts +31 -0
- package/src/channel.message-adapter.test.ts +145 -0
- package/src/channel.runtime.ts +259 -0
- package/src/channel.ts +192 -0
- package/src/config-schema.ts +54 -0
- package/src/core.test.ts +298 -0
- package/src/doctor-contract.ts +9 -0
- package/src/doctor.test.ts +46 -0
- package/src/doctor.ts +10 -0
- package/src/logger-runtime.ts +1 -0
- package/src/monitor/approval-runtime.ts +363 -0
- package/src/monitor/approval.test.ts +33 -0
- package/src/monitor/approval.ts +283 -0
- package/src/monitor/authorization.ts +30 -0
- package/src/monitor/cites.ts +54 -0
- package/src/monitor/discovery.ts +68 -0
- package/src/monitor/history.ts +226 -0
- package/src/monitor/index.ts +1523 -0
- package/src/monitor/media.test.ts +80 -0
- package/src/monitor/media.ts +156 -0
- package/src/monitor/processed-messages.test.ts +58 -0
- package/src/monitor/processed-messages.ts +89 -0
- package/src/monitor/settings-helpers.test.ts +113 -0
- package/src/monitor/settings-helpers.ts +158 -0
- package/src/monitor/utils.ts +402 -0
- package/src/runtime.ts +9 -0
- package/src/security.test.ts +658 -0
- package/src/session-route.ts +40 -0
- package/src/settings.ts +391 -0
- package/src/setup-core.ts +231 -0
- package/src/setup-surface.ts +99 -0
- package/src/targets.ts +102 -0
- package/src/tlon-api.test.ts +572 -0
- package/src/tlon-api.ts +389 -0
- package/src/types.ts +160 -0
- package/src/urbit/auth.ssrf.test.ts +45 -0
- package/src/urbit/auth.ts +48 -0
- package/src/urbit/base-url.test.ts +48 -0
- package/src/urbit/base-url.ts +61 -0
- package/src/urbit/channel-ops.test.ts +36 -0
- package/src/urbit/channel-ops.ts +149 -0
- package/src/urbit/context.ts +50 -0
- package/src/urbit/errors.ts +51 -0
- package/src/urbit/fetch.ts +38 -0
- package/src/urbit/foreigns.ts +49 -0
- package/src/urbit/send.test.ts +83 -0
- package/src/urbit/send.ts +228 -0
- package/src/urbit/sse-client.test.ts +234 -0
- package/src/urbit/sse-client.ts +492 -0
- package/src/urbit/story.ts +332 -0
- package/src/urbit/upload.test.ts +155 -0
- package/src/urbit/upload.ts +60 -0
- package/test-api.ts +1 -0
- package/tsconfig.json +16 -0
- package/api.js +0 -7
- package/bundled-skills/@tloncorp/tlon-skill/SKILL.md +0 -501
- package/bundled-skills/@tloncorp/tlon-skill/bin/tlon.js +0 -7
- package/bundled-skills/@tloncorp/tlon-skill/package.json +0 -40
- package/bundled-skills/@tloncorp/tlon-skill/scripts/postinstall.js +0 -7
- package/channel-plugin-api.js +0 -7
- package/doctor-contract-api.js +0 -7
- package/index.js +0 -7
- package/runtime-api.js +0 -7
- package/setup-api.js +0 -7
- package/setup-entry.js +0 -7
- package/test-api.js +0 -7
|
@@ -1,501 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: tlon
|
|
3
|
-
description: Interact with Tlon/Urbit API. Use for reading activity, message history, contacts, channels, and groups. Also for group/channel administration, profile management, and exposing content to the clearweb.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Tlon Skill
|
|
7
|
-
|
|
8
|
-
Use the `tlon` command for reading data, managing channels/groups/contacts, and administration.
|
|
9
|
-
|
|
10
|
-
## OpenClaw
|
|
11
|
-
|
|
12
|
-
When running as an OpenClaw skill, use the built-in `message` tool for sending outbound messages (DMs and channel posts). The `tlon` command is for reading data, administration, and management — not for sending messages. The `message` tool routes through the proper delivery infrastructure (threading, bot profile, rate limiting).
|
|
13
|
-
|
|
14
|
-
### Diary / Notebook Thread Replies
|
|
15
|
-
|
|
16
|
-
Tlon diary/notebook channels are special: a channel-level `send` creates a **new notebook post/note**. Do **not** use `message` with `action: "send"` in a diary channel unless you intentionally want to create a new notebook post.
|
|
17
|
-
|
|
18
|
-
For normal conversation inside an existing diary/notebook post, use the `message` tool with `action: "reply"` and reply to the **parent diary post id**, not the newest reply id.
|
|
19
|
-
|
|
20
|
-
Working pattern:
|
|
21
|
-
|
|
22
|
-
```json
|
|
23
|
-
{
|
|
24
|
-
"action": "reply",
|
|
25
|
-
"channel": "tlon",
|
|
26
|
-
"target": "diary/~host/slug",
|
|
27
|
-
"messageId": "170.141.184.507.950.303.933.087.606.997.052.817.408",
|
|
28
|
-
"message": "Reply text here"
|
|
29
|
-
}
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
Important details:
|
|
33
|
-
- Use the dotted `@ud` post id format when available.
|
|
34
|
-
- `messageId` should be the parent notebook post/thread id.
|
|
35
|
-
- After sending, verify with `tlon messages post <diary-nest> <parent-post-id>` when correctness matters.
|
|
36
|
-
- If the tool reports success but the reply is not visible under the parent post, treat it as a delivery/plugin issue and do not claim success until verified.
|
|
37
|
-
|
|
38
|
-
## Installation
|
|
39
|
-
|
|
40
|
-
**npm (Node.js):**
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
npm install @tloncorp/tlon-skill
|
|
44
|
-
tlon channels groups
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
**Direct binary (no Node required):**
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
curl -L https://registry.npmjs.org/@tloncorp/tlon-skill-darwin-arm64/-/tlon-skill-darwin-arm64-0.1.0.tgz | tar -xz
|
|
51
|
-
./package/tlon channels groups
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
Replace `darwin-arm64` with `darwin-x64` or `linux-x64` as needed.
|
|
55
|
-
|
|
56
|
-
## Configuration
|
|
57
|
-
|
|
58
|
-
**CLI Flags (highest priority):**
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
# Cookie-based auth (fastest - ship parsed from cookie name)
|
|
62
|
-
tlon --url https://your-ship.tlon.network --cookie "urbauth-~your-ship=0v..." <command>
|
|
63
|
-
|
|
64
|
-
# Code-based auth (requires url + ship + code)
|
|
65
|
-
tlon --url https://your-ship.tlon.network --ship ~your-ship --code sampel-ticlyt-migfun-falmel <command>
|
|
66
|
-
|
|
67
|
-
# Or load from a JSON config file
|
|
68
|
-
tlon --config ~/ships/my-ship.json <command>
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
Config file format:
|
|
72
|
-
|
|
73
|
-
```json
|
|
74
|
-
// Cookie-based (ship derived from cookie)
|
|
75
|
-
{"url": "...", "cookie": "urbauth-~ship=..."}
|
|
76
|
-
|
|
77
|
-
// Code-based
|
|
78
|
-
{"url": "...", "ship": "~...", "code": "..."}
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
**Environment Variables:**
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
# Cookie-based (ship derived from cookie)
|
|
85
|
-
export URBIT_URL="https://your-ship.tlon.network"
|
|
86
|
-
export URBIT_COOKIE="urbauth-~your-ship=0v..."
|
|
87
|
-
|
|
88
|
-
# Code-based
|
|
89
|
-
export URBIT_URL="https://your-ship.tlon.network"
|
|
90
|
-
export URBIT_SHIP="~your-ship"
|
|
91
|
-
export URBIT_CODE="sampel-ticlyt-migfun-falmel"
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
**OpenClaw:** If configured with a Tlon channel, credentials load automatically.
|
|
95
|
-
|
|
96
|
-
**Resolution order:** CLI flags → `TLON_CONFIG_FILE` → `URL + COOKIE` → `URL + SHIP + CODE` → `--ship` with cache → OpenClaw config → cached ships (auto-select if only one)
|
|
97
|
-
|
|
98
|
-
**Cookie vs Code:**
|
|
99
|
-
|
|
100
|
-
- **Cookie-based:** Uses pre-authenticated session cookie. Ship is parsed from the cookie name (`urbauth-~ship=...`). Fastest option.
|
|
101
|
-
- **Code-based:** Performs login to get session cookie. Requires URL + ship + code.
|
|
102
|
-
|
|
103
|
-
You can provide both cookie and code — cookie is used first, code serves as fallback if cookie expires.
|
|
104
|
-
|
|
105
|
-
## Cookie Caching
|
|
106
|
-
|
|
107
|
-
The skill automatically caches auth cookies to `~/.tlon/cache/<ship>.json` after successful authentication. This makes subsequent invocations much faster by skipping the login request.
|
|
108
|
-
|
|
109
|
-
**How it works:**
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
# First time - authenticates and caches
|
|
113
|
-
$ tlon --url https://zod.tlon.network --ship ~zod --code abcd-efgh contacts self
|
|
114
|
-
~zod
|
|
115
|
-
Note: Credentials cached for ~zod. Next time just run: tlon <command>
|
|
116
|
-
|
|
117
|
-
# After that - no flags needed (if only one cached ship)
|
|
118
|
-
$ tlon contacts self
|
|
119
|
-
~zod
|
|
120
|
-
|
|
121
|
-
# With multiple cached ships - specify which one
|
|
122
|
-
$ tlon --ship ~zod contacts self
|
|
123
|
-
$ tlon --ship ~bus contacts self
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
**Cache behavior:**
|
|
127
|
-
|
|
128
|
-
- Cached cookies are URL-specific (won't use a cookie for the wrong host)
|
|
129
|
-
- If only one ship is cached, it's auto-selected (no flags needed)
|
|
130
|
-
- If multiple ships are cached, you'll be prompted to specify with `--ship`
|
|
131
|
-
- The skill reminds you when you pass credentials that aren't needed
|
|
132
|
-
|
|
133
|
-
**Clear cache:** `rm ~/.tlon/cache/*.json`
|
|
134
|
-
|
|
135
|
-
## Multi-Ship Usage
|
|
136
|
-
|
|
137
|
-
If you have credentials for multiple ships, you can use this skill to operate on behalf of any of them. This is useful for:
|
|
138
|
-
|
|
139
|
-
- **Managing multiple identities** — switch between ships without changing environment variables
|
|
140
|
-
- **Bot operations** — act as a bot ship while authenticated as yourself
|
|
141
|
-
- **Moon management** — operate moons from their parent planet
|
|
142
|
-
|
|
143
|
-
Simply pass the target ship's credentials via CLI flags:
|
|
144
|
-
|
|
145
|
-
```bash
|
|
146
|
-
# Post to a channel as ~other-ship
|
|
147
|
-
tlon --url https://other-ship.tlon.network --ship ~other-ship --code their-access-code \
|
|
148
|
-
posts send chat/~host/channel "Hello from other-ship"
|
|
149
|
-
|
|
150
|
-
# Or keep credentials in config files
|
|
151
|
-
tlon --config ~/ships/bot.json channels groups
|
|
152
|
-
tlon --config ~/ships/moon.json contacts self
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
## Commands
|
|
156
|
-
|
|
157
|
-
### Activity
|
|
158
|
-
|
|
159
|
-
Check recent notifications and unread counts. Ships are shown with nicknames when available.
|
|
160
|
-
|
|
161
|
-
```bash
|
|
162
|
-
tlon activity mentions --limit 10 # Recent mentions (max 25)
|
|
163
|
-
tlon activity replies --limit 10 # Recent replies (max 25)
|
|
164
|
-
tlon activity all --limit 10 # All recent activity (max 25)
|
|
165
|
-
tlon activity unreads # Unread counts per channel
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
### Channels
|
|
169
|
-
|
|
170
|
-
List and manage channels. DMs show nicknames when available.
|
|
171
|
-
|
|
172
|
-
```bash
|
|
173
|
-
tlon channels dms # List DM contacts (with nicknames)
|
|
174
|
-
tlon channels groups # List subscribed groups
|
|
175
|
-
tlon channels all # List everything
|
|
176
|
-
tlon channels info chat/~host/slug # Get channel details
|
|
177
|
-
tlon channels create ~host/slug "Projects" --kind chat # Create a group channel
|
|
178
|
-
tlon channels rename chat/~host/slug "New Title" # Rename a channel
|
|
179
|
-
tlon channels update chat/~host/slug --title "New Title" # Update metadata
|
|
180
|
-
tlon channels delete chat/~host/slug # Delete a channel
|
|
181
|
-
|
|
182
|
-
# Writers (who can post)
|
|
183
|
-
tlon channels add-writers chat/~host/slug admin member # Add write access
|
|
184
|
-
tlon channels del-writers chat/~host/slug member # Remove write access
|
|
185
|
-
|
|
186
|
-
# Readers (who can view - requires group flag)
|
|
187
|
-
tlon channels add-readers ~host/group chat/~host/slug admin # Restrict viewing
|
|
188
|
-
tlon channels del-readers ~host/group chat/~host/slug admin # Open viewing
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
Help works for both the command and subcommands:
|
|
192
|
-
|
|
193
|
-
```bash
|
|
194
|
-
tlon channels --help
|
|
195
|
-
tlon channels create --help
|
|
196
|
-
tlon channels rename --help
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
Notes on permissions:
|
|
200
|
-
|
|
201
|
-
- Empty writers list = anyone in the group can post (default for chat)
|
|
202
|
-
- Empty readers list = anyone in the group can view (default)
|
|
203
|
-
- Diaries default to admin-only writers
|
|
204
|
-
- Roles must exist in the group (use `tlon groups add-role` first)
|
|
205
|
-
|
|
206
|
-
### Contacts
|
|
207
|
-
|
|
208
|
-
Manage contacts and profiles.
|
|
209
|
-
|
|
210
|
-
```bash
|
|
211
|
-
tlon contacts list # List all contacts
|
|
212
|
-
tlon contacts self # Get your own profile
|
|
213
|
-
tlon contacts get ~sampel # Get a contact's profile
|
|
214
|
-
tlon contacts sync ~ship1 ~ship2 # Fetch/sync profiles
|
|
215
|
-
tlon contacts add ~sampel # Add a contact
|
|
216
|
-
tlon contacts remove ~sampel # Remove a contact
|
|
217
|
-
tlon contacts update-profile --nickname "My Name" # Update your profile
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
Options: `--nickname`, `--bio`, `--status`, `--avatar`, `--cover`
|
|
221
|
-
|
|
222
|
-
### Groups
|
|
223
|
-
|
|
224
|
-
Full group management.
|
|
225
|
-
|
|
226
|
-
```bash
|
|
227
|
-
# Basics
|
|
228
|
-
tlon groups list # List your groups
|
|
229
|
-
tlon groups info ~host/slug # Get group details
|
|
230
|
-
tlon groups create "Name" [--description "..."] # Create a group
|
|
231
|
-
tlon groups create-owned "Name" --owner ~ship [--description "..."] # Create group, invite owner, make owner admin
|
|
232
|
-
tlon groups join ~host/slug # Join public/invited group, or request invite if private
|
|
233
|
-
tlon groups request-invite ~host/slug # Request invite to a private group
|
|
234
|
-
tlon groups accept-invite ~host/slug # Accept an existing group invite
|
|
235
|
-
tlon groups reject-invite ~host/slug # Reject an existing group invite
|
|
236
|
-
tlon groups cancel-join ~host/slug # Cancel a pending join
|
|
237
|
-
tlon groups rescind-request ~host/slug # Cancel an invite request
|
|
238
|
-
tlon groups leave ~host/slug # Leave a group
|
|
239
|
-
tlon groups delete ~host/slug # Delete (host only)
|
|
240
|
-
tlon groups update ~host/slug --title "..." [--description "..."]
|
|
241
|
-
|
|
242
|
-
# Members (shown with nicknames when available)
|
|
243
|
-
tlon groups invite ~host/slug ~ship1 ~ship2 # Invite members
|
|
244
|
-
tlon groups revoke-invite ~host/slug ~ship1 # Revoke pending member invite
|
|
245
|
-
tlon groups kick ~host/slug ~ship1 # Kick members
|
|
246
|
-
tlon groups ban ~host/slug ~ship1 # Ban members
|
|
247
|
-
tlon groups unban ~host/slug ~ship1 # Unban members
|
|
248
|
-
tlon groups accept-join ~host/slug ~ship1 # Approve a member join request
|
|
249
|
-
tlon groups reject-join ~host/slug ~ship1 # Deny a member join request
|
|
250
|
-
tlon groups set-privacy ~host/slug public|private|secret # Set privacy
|
|
251
|
-
|
|
252
|
-
# Roles
|
|
253
|
-
tlon groups add-role ~host/slug role-id --title "..." # Create a role
|
|
254
|
-
tlon groups delete-role ~host/slug role-id # Delete a role
|
|
255
|
-
tlon groups update-role ~host/slug role-id --title "..." # Update a role
|
|
256
|
-
tlon groups assign-role ~host/slug role-id ~ship1 # Assign role
|
|
257
|
-
tlon groups remove-role ~host/slug role-id ~ship1 # Remove role
|
|
258
|
-
|
|
259
|
-
# Admin
|
|
260
|
-
tlon groups promote ~host/slug ~ship1 [~ship2 ...] # Promote member(s) to admin
|
|
261
|
-
tlon groups demote ~host/slug ~ship1 [~ship2 ...] # Demote member(s) from admin
|
|
262
|
-
|
|
263
|
-
Roles vs Admin:
|
|
264
|
-
- Regular roles are for organizing members and controlling channel read/write permissions.
|
|
265
|
-
- Admin is a special privilege on top of a role. Admins can manage group settings,
|
|
266
|
-
channels, members, and roles.
|
|
267
|
-
- `promote` creates an "admin" role (if one doesn't exist), grants it admin privileges,
|
|
268
|
-
and assigns it to the specified members. `demote` removes that role from them.
|
|
269
|
-
- To grant admin to members who already share a role, use `set-admin` on that role
|
|
270
|
-
via the backend directly (not yet exposed in the Tlon app UI).
|
|
271
|
-
|
|
272
|
-
# Channels
|
|
273
|
-
tlon groups add-channel ~host/slug "Name" [--kind chat|diary|heap]
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
`tlon groups add-channel` remains supported, but for agent/tool use prefer the more discoverable channel-centric form:
|
|
277
|
-
|
|
278
|
-
```bash
|
|
279
|
-
tlon channels create ~host/slug "Projects" --kind chat
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
Help works here too:
|
|
283
|
-
|
|
284
|
-
```bash
|
|
285
|
-
tlon groups --help
|
|
286
|
-
tlon groups add-channel --help
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
Group format: `~host-ship/group-slug`
|
|
290
|
-
|
|
291
|
-
Join behavior:
|
|
292
|
-
- `join` first checks whether you are already a member, then checks foreign/unjoined group state for a valid invite.
|
|
293
|
-
- Invited groups and public groups use the backend join action.
|
|
294
|
-
- Private groups without an invite use the invite-request action.
|
|
295
|
-
- Secret groups require an invite.
|
|
296
|
-
|
|
297
|
-
### Hooks
|
|
298
|
-
|
|
299
|
-
Manage channel hooks — functions that run on triggers (posts, replies, reactions, crons).
|
|
300
|
-
|
|
301
|
-
```bash
|
|
302
|
-
# List and inspect
|
|
303
|
-
tlon hooks list # List all hooks
|
|
304
|
-
tlon hooks get 0v1a.2b3c4 # Get hook details and source
|
|
305
|
-
|
|
306
|
-
# Manage hooks
|
|
307
|
-
tlon hooks init my-hook --type on-post # Create starter template (on-post|cron|moderation)
|
|
308
|
-
tlon hooks add my-hook ./my-hook.hoon # Add a new hook from file
|
|
309
|
-
tlon hooks edit 0v1a.2b3c4 --name "New Name" # Rename a hook
|
|
310
|
-
tlon hooks edit 0v1a.2b3c4 --src ./updated.hoon # Update source
|
|
311
|
-
tlon hooks delete 0v1a.2b3c4 # Delete a hook
|
|
312
|
-
|
|
313
|
-
# Configure for channels
|
|
314
|
-
tlon hooks order chat/~host/slug 0v1a 0v2b 0v3c # Set execution order
|
|
315
|
-
tlon hooks config 0v1a chat/~host/slug key1=val1 # Configure hook instance
|
|
316
|
-
|
|
317
|
-
# Scheduled execution
|
|
318
|
-
tlon hooks cron 0v1a ~h1 # Run hourly (global)
|
|
319
|
-
tlon hooks cron 0v1a ~m30 --nest chat/~host/slug # Run every 30m for channel
|
|
320
|
-
tlon hooks rest 0v1a # Stop cron job
|
|
321
|
-
```
|
|
322
|
-
|
|
323
|
-
Notes:
|
|
324
|
-
|
|
325
|
-
- Hook IDs are @uv format (e.g., `0v1a.2b3c4...`)
|
|
326
|
-
- Schedules use @dr format: `~h1` (1 hour), `~m30` (30 minutes), `~d1` (1 day)
|
|
327
|
-
- Hooks run in order when triggered; use `order` to set priority
|
|
328
|
-
- Use `config` to pass channel-specific settings to a hook instance
|
|
329
|
-
|
|
330
|
-
**Writing Hooks:** See `references/hooks.md` for full documentation on writing hooks, including:
|
|
331
|
-
|
|
332
|
-
- Event types (`on-post`, `on-reply`, `cron`, `wake`)
|
|
333
|
-
- Bowl context (channel, group, config access)
|
|
334
|
-
- Effects (channel actions, group actions, scheduled wakes)
|
|
335
|
-
- Config handling with clam (`;;`)
|
|
336
|
-
|
|
337
|
-
**Examples:** See `references/hooks-examples/` for starter templates:
|
|
338
|
-
|
|
339
|
-
- `auto-react.hoon` — React to new posts with emoji
|
|
340
|
-
- `delete-old-posts.hoon` — Cron job to clean up old messages
|
|
341
|
-
- `word-filter.hoon` — Block posts containing banned words
|
|
342
|
-
|
|
343
|
-
### Messages
|
|
344
|
-
|
|
345
|
-
Read and search message history. Authors are shown with nicknames when available.
|
|
346
|
-
|
|
347
|
-
```bash
|
|
348
|
-
tlon messages dm ~sampel --limit 20 # DM history (max 50)
|
|
349
|
-
tlon messages channel chat/~host/slug --limit 20 # Channel history (max 50)
|
|
350
|
-
tlon messages search "query" --channel chat/~host/slug # Search messages
|
|
351
|
-
tlon messages context chat/~host/slug 170.141... --limit 5 # Messages around a post
|
|
352
|
-
tlon messages post chat/~host/slug 170.141... # Fetch single post with replies
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
Options: `--limit N`, `--resolve-cites`
|
|
356
|
-
|
|
357
|
-
The `context` command fetches N messages before and after a given post ID — useful for
|
|
358
|
-
finding surrounding conversation when you have a post from search or activity.
|
|
359
|
-
For DMs, use the ship name as the channel: `tlon messages context ~sampel 170.141...`
|
|
360
|
-
|
|
361
|
-
The `post` command fetches a single post with its replies/thread. For DM posts,
|
|
362
|
-
pass `--author ~ship` (required for DM lookups).
|
|
363
|
-
|
|
364
|
-
**Tip:** Use `search` to find a message, then `context` with its ID to see the surrounding conversation.
|
|
365
|
-
|
|
366
|
-
### DMs
|
|
367
|
-
|
|
368
|
-
Manage direct messages — reactions, invites, and deletions.
|
|
369
|
-
|
|
370
|
-
```bash
|
|
371
|
-
# Management
|
|
372
|
-
tlon dms react ~sampel ~author/170.141... "👍" # React to a DM
|
|
373
|
-
tlon dms unreact ~sampel ~author/170.141... # Remove reaction
|
|
374
|
-
tlon dms delete ~sampel ~author/170.141... # Delete a DM
|
|
375
|
-
tlon dms accept ~sampel # Accept DM invite
|
|
376
|
-
tlon dms decline ~sampel # Decline DM invite
|
|
377
|
-
```
|
|
378
|
-
|
|
379
|
-
### Expose
|
|
380
|
-
|
|
381
|
-
Publish Tlon content to the clearweb via the %expose agent.
|
|
382
|
-
|
|
383
|
-
```bash
|
|
384
|
-
tlon expose list # List all exposed content
|
|
385
|
-
tlon expose show chat/~host/slug/170.141... # Expose a post publicly
|
|
386
|
-
tlon expose hide chat/~host/slug/170.141... # Hide an exposed post
|
|
387
|
-
tlon expose check diary/~host/blog/170.141... # Check if a post is exposed
|
|
388
|
-
tlon expose url diary/~host/blog/170.141... # Get the public URL
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
Cite path formats:
|
|
392
|
-
|
|
393
|
-
- Simplified: `chat/~host/channel/170.141...` (auto-expands)
|
|
394
|
-
- Full: `/1/chan/chat/~host/channel/msg/170.141...`
|
|
395
|
-
|
|
396
|
-
Channel kinds map to content types: chat→msg, diary→note, heap→curio
|
|
397
|
-
|
|
398
|
-
### Posts
|
|
399
|
-
|
|
400
|
-
Manage channel posts (reactions, edits, deletes).
|
|
401
|
-
|
|
402
|
-
```bash
|
|
403
|
-
tlon posts react chat/~host/slug 170.141... "👍" # React to a post
|
|
404
|
-
tlon posts unreact chat/~host/slug 170.141... # Remove reaction
|
|
405
|
-
tlon posts edit chat/~host/slug 170.141... "New text" # Edit with plain text
|
|
406
|
-
tlon posts edit diary/~host/slug 170.141... --title "T" --image <url> --content story.json # Edit notebook
|
|
407
|
-
tlon posts delete chat/~host/slug 170.141... # Delete a post
|
|
408
|
-
```
|
|
409
|
-
|
|
410
|
-
Edit options for notebooks: `--title`, `--image` (cover URL), `--content` (Story JSON file for rich formatting).
|
|
411
|
-
|
|
412
|
-
### Notebook
|
|
413
|
-
|
|
414
|
-
Post to diary/notebook channels.
|
|
415
|
-
|
|
416
|
-
```bash
|
|
417
|
-
tlon notebook diary/~host/slug "Title" # Post with no body
|
|
418
|
-
tlon notebook diary/~host/slug "Title" --content story.json # Post with Story JSON
|
|
419
|
-
tlon notebook diary/~host/slug "Title" --markdown post.md # Post with Markdown
|
|
420
|
-
cat post.md | tlon notebook diary/~host/slug "Title" --markdown-stdin
|
|
421
|
-
tlon notebook diary/~host/slug "Title" --image <url> # Post with cover image
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
The `--content` file should be **Urbit Story JSON**: an array of verses accepted by the ship's `story-json` decoder. Use `--markdown` for Markdown files instead of passing Markdown or editor-export JSON through `--content`.
|
|
425
|
-
|
|
426
|
-
Working examples:
|
|
427
|
-
|
|
428
|
-
```json
|
|
429
|
-
[{"inline": ["Hello world"]}]
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
```json
|
|
433
|
-
[{"block": {"header": {"tag": "h1", "content": ["Title"]}}}]
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
```json
|
|
437
|
-
[{"inline": ["Use ", {"inline-code": "ha-q"}, " for entity queries."]}]
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
Important gotcha:
|
|
441
|
-
- Do **not** assume newer block-editor JSON shapes or arbitrary markdown-export JSON will work.
|
|
442
|
-
- If posting fails with a `channel-action-2` cast error mentioning `content -> add -> post -> action -> channel`, the first thing to check is whether the content file matches the ship's Story JSON shape.
|
|
443
|
-
- When debugging, post a minimal one-verse story first so you do not create duplicate full notebook posts.
|
|
444
|
-
|
|
445
|
-
See the ship-side decoder and types here:
|
|
446
|
-
- `tlon-apps/desk/lib/story-json.hoon`
|
|
447
|
-
- [Story types in tlon-apps](https://github.com/tloncorp/tlon-apps/blob/develop/packages/shared/src/urbit/content.ts)
|
|
448
|
-
|
|
449
|
-
### Upload
|
|
450
|
-
|
|
451
|
-
Upload files to Tlon storage from a URL, local path, or stdin.
|
|
452
|
-
|
|
453
|
-
```bash
|
|
454
|
-
tlon upload https://example.com/image.png # Upload from URL
|
|
455
|
-
tlon upload ./photo.jpg # Upload local file
|
|
456
|
-
tlon upload ~/Pictures/screenshot.png # Upload with absolute path
|
|
457
|
-
tlon upload ./mystery-file -t image/webp # Override content type
|
|
458
|
-
cat image.png | tlon upload --stdin -t image/png # Upload from stdin
|
|
459
|
-
```
|
|
460
|
-
|
|
461
|
-
Options: `-t`/`--type` (override MIME type), `--stdin` (read from stdin)
|
|
462
|
-
|
|
463
|
-
Content type is auto-detected from file extension for local files. For stdin, `-t` is recommended (defaults to `application/octet-stream`).
|
|
464
|
-
|
|
465
|
-
Returns the uploaded URL for use in posts, profiles, etc.
|
|
466
|
-
|
|
467
|
-
### Settings (OpenClaw)
|
|
468
|
-
|
|
469
|
-
Manage OpenClaw's Tlon plugin config via Urbit settings-store. Changes apply immediately without gateway restart.
|
|
470
|
-
|
|
471
|
-
```bash
|
|
472
|
-
tlon settings get # Show all settings
|
|
473
|
-
tlon settings set <key> <json-value> # Set a value
|
|
474
|
-
tlon settings delete <key> # Delete a setting
|
|
475
|
-
|
|
476
|
-
# DM allowlist
|
|
477
|
-
tlon settings allow-dm ~ship # Add to DM allowlist
|
|
478
|
-
tlon settings remove-dm ~ship # Remove from allowlist
|
|
479
|
-
|
|
480
|
-
# Channel controls
|
|
481
|
-
tlon settings allow-channel chat/~host/slug # Add to watch list
|
|
482
|
-
tlon settings remove-channel chat/~host/slug # Remove from watch list
|
|
483
|
-
tlon settings open-channel chat/~host/slug # Set channel to open
|
|
484
|
-
tlon settings restrict-channel chat/~host/slug [~ship1] # Set restricted
|
|
485
|
-
|
|
486
|
-
# Authorization
|
|
487
|
-
tlon settings authorize-ship ~ship # Add to default auth
|
|
488
|
-
tlon settings deauthorize-ship ~ship # Remove from auth
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
## Notes
|
|
492
|
-
|
|
493
|
-
- Ship names should include `~` prefix
|
|
494
|
-
- Post IDs are @ud format with dots (e.g. `170.141.184.507...`)
|
|
495
|
-
- DM post IDs include author prefix (`~ship/170.141...`)
|
|
496
|
-
- Channel nests: `<kind>/~<host>/<name>` (chat, diary, or heap)
|
|
497
|
-
|
|
498
|
-
## Limits
|
|
499
|
-
|
|
500
|
-
- Activity: max 25 items
|
|
501
|
-
- Messages: max 50 items
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../../../../../dist/extensions/tlon/bundled-skills/@tloncorp/tlon-skill/bin/tlon.js";
|
|
2
|
-
import * as module from "../../../../../../../dist/extensions/tlon/bundled-skills/@tloncorp/tlon-skill/bin/tlon.js";
|
|
3
|
-
let defaultExport = "default" in module ? module.default : module;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
|
@@ -1,40 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@tloncorp/tlon-skill",
|
|
3
|
-
"version": "0.4.0",
|
|
4
|
-
"description": "Tlon/Urbit skill for OpenClaw agents",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"tlon": "./bin/tlon.js"
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"bin/",
|
|
11
|
-
"scripts/postinstall.js",
|
|
12
|
-
"SKILL.md",
|
|
13
|
-
"references/"
|
|
14
|
-
],
|
|
15
|
-
"scripts": {
|
|
16
|
-
"build": "node scripts/build.js",
|
|
17
|
-
"build:all": "node scripts/build-all.js",
|
|
18
|
-
"dev:link": "bun run build:all && cp \"npm/$(node -e 'console.log(process.platform + \"-\" + process.arch)')/tlon\" bin/",
|
|
19
|
-
"test": "bun test",
|
|
20
|
-
"version": "node scripts/bump-version.js",
|
|
21
|
-
"postinstall": "node scripts/postinstall.js"
|
|
22
|
-
},
|
|
23
|
-
"optionalDependencies": {
|
|
24
|
-
"@tloncorp/tlon-skill-darwin-arm64": "0.4.0",
|
|
25
|
-
"@tloncorp/tlon-skill-darwin-x64": "0.4.0",
|
|
26
|
-
"@tloncorp/tlon-skill-linux-x64": "0.4.0",
|
|
27
|
-
"@tloncorp/tlon-skill-linux-arm64": "0.4.0"
|
|
28
|
-
},
|
|
29
|
-
"devDependencies": {
|
|
30
|
-
"@tloncorp/api": "^0.0.4",
|
|
31
|
-
"@urbit/aura": "^3.0.0",
|
|
32
|
-
"@types/node": "^22.0.0",
|
|
33
|
-
"typescript": "^5.9.3"
|
|
34
|
-
},
|
|
35
|
-
"repository": {
|
|
36
|
-
"type": "git",
|
|
37
|
-
"url": "https://github.com/tloncorp/tlon-skill.git"
|
|
38
|
-
},
|
|
39
|
-
"license": "MIT"
|
|
40
|
-
}
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../../../../../dist/extensions/tlon/bundled-skills/@tloncorp/tlon-skill/scripts/postinstall.js";
|
|
2
|
-
import * as module from "../../../../../../../dist/extensions/tlon/bundled-skills/@tloncorp/tlon-skill/scripts/postinstall.js";
|
|
3
|
-
let defaultExport = "default" in module ? module.default : module;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
package/channel-plugin-api.js
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../dist/extensions/tlon/channel-plugin-api.js";
|
|
2
|
-
import * as module from "../../../dist/extensions/tlon/channel-plugin-api.js";
|
|
3
|
-
let defaultExport = "default" in module ? module.default : module;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
package/doctor-contract-api.js
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../dist/extensions/tlon/doctor-contract-api.js";
|
|
2
|
-
import * as module from "../../../dist/extensions/tlon/doctor-contract-api.js";
|
|
3
|
-
let defaultExport = "default" in module ? module.default : module;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
package/index.js
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../dist/extensions/tlon/index.js";
|
|
2
|
-
import defaultModule from "../../../dist/extensions/tlon/index.js";
|
|
3
|
-
let defaultExport = defaultModule;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
package/runtime-api.js
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../dist/extensions/tlon/runtime-api.js";
|
|
2
|
-
import * as module from "../../../dist/extensions/tlon/runtime-api.js";
|
|
3
|
-
let defaultExport = "default" in module ? module.default : module;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
package/setup-api.js
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../dist/extensions/tlon/setup-api.js";
|
|
2
|
-
import * as module from "../../../dist/extensions/tlon/setup-api.js";
|
|
3
|
-
let defaultExport = "default" in module ? module.default : module;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
package/setup-entry.js
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../dist/extensions/tlon/setup-entry.js";
|
|
2
|
-
import defaultModule from "../../../dist/extensions/tlon/setup-entry.js";
|
|
3
|
-
let defaultExport = defaultModule;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|
package/test-api.js
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
export * from "../../../dist/extensions/tlon/test-api.js";
|
|
2
|
-
import * as module from "../../../dist/extensions/tlon/test-api.js";
|
|
3
|
-
let defaultExport = "default" in module ? module.default : module;
|
|
4
|
-
for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
|
|
5
|
-
defaultExport = defaultExport.default;
|
|
6
|
-
}
|
|
7
|
-
export { defaultExport as default };
|