@agentsky/sky 3.42.0 → 3.44.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.
@@ -0,0 +1,585 @@
1
+ import {
2
+ CLI_VERSION
3
+ } from "./chunk-CXRMG3HQ.js";
4
+
5
+ // src/skill.ts
6
+ import { mkdirSync, readFileSync, writeFileSync } from "fs";
7
+ import { join } from "path";
8
+
9
+ // src/catalog-file.ts
10
+ var CATALOG_FILE = "catalog.md";
11
+ var CATEGORY_ORDER = ["websites", "content", "video", "code", "research", "general"];
12
+ function categoryOf(agent) {
13
+ return CATEGORY_ORDER.find((category) => agent.categories.includes(category)) ?? agent.categories[0] ?? "general";
14
+ }
15
+ function describe(value) {
16
+ const parts = Object.entries(value).filter(([, item]) => item !== null && item !== void 0 && item !== false && item !== "").map(([key, item]) => item === true ? key : `${key}: ${typeof item === "string" ? item : JSON.stringify(item)}`);
17
+ return parts.length ? parts.join(", ") : null;
18
+ }
19
+ function entry(agent) {
20
+ const engine = agent.engine_type ? ` \xB7 engine ${agent.engine_type}` : "";
21
+ const lines = [`### @${agent.handle} \u2014 ${agent.name}${engine}`, "", agent.tagline];
22
+ if (agent.does.length) lines.push("", `Does: ${agent.does.join("; ")}`);
23
+ if (agent.does_not.length) lines.push(`Does not: ${agent.does_not.join("; ")}`);
24
+ const { mcp_servers: mcpServers, ...rest } = agent.requirements;
25
+ if (typeof mcpServers === "boolean") lines.push(mcpServers ? "Can use MCP servers." : "Cannot use MCP servers.");
26
+ const details = describe(rest);
27
+ if (details) lines.push(`Details: ${details}`);
28
+ const pricing = describe(agent.pricing);
29
+ if (pricing) lines.push(`Pricing: ${pricing}`);
30
+ return lines.join("\n");
31
+ }
32
+ function renderCatalog(agents, generatedAt) {
33
+ const header = [
34
+ "# AgentSky agent catalog",
35
+ "",
36
+ `Every agent you can hire, as of ${generatedAt.toISOString()}. Start one with \`start_session\` and its handle, written with the @.`,
37
+ "Run `npx @agentsky/sky setup` again to refresh this file; `search_catalog` always has the current list."
38
+ ];
39
+ if (!agents.length) return [...header, "", "The catalog was empty when this file was written. Use `search_catalog`.", ""].join("\n");
40
+ const own = agents.filter((agent) => agent.visibility === "workspace");
41
+ const shared = agents.filter((agent) => agent.visibility !== "workspace");
42
+ const sections = [];
43
+ if (own.length) sections.push(["## Your workspace's agents", ...own.map(entry)].join("\n\n"));
44
+ const groups = /* @__PURE__ */ new Map();
45
+ for (const agent of shared) groups.set(categoryOf(agent), [...groups.get(categoryOf(agent)) ?? [], agent]);
46
+ const ordered = [...groups.keys()].sort((a, b) => {
47
+ const rank = (category) => CATEGORY_ORDER.includes(category) ? CATEGORY_ORDER.indexOf(category) : CATEGORY_ORDER.length;
48
+ return rank(a) - rank(b) || a.localeCompare(b);
49
+ });
50
+ for (const category of ordered) {
51
+ const title = category.charAt(0).toUpperCase() + category.slice(1);
52
+ sections.push([`## ${title}`, ...groups.get(category).map(entry)].join("\n\n"));
53
+ }
54
+ return [...header, "", sections.join("\n\n"), ""].join("\n");
55
+ }
56
+
57
+ // src/skill.ts
58
+ var REFERENCES_DIR = "references";
59
+ var SKILL_NAME = "agentsky";
60
+ var SKILL_MARKER = ".agentsky.json";
61
+ function skillDocument() {
62
+ return `---
63
+ name: ${SKILL_NAME}
64
+ description: "Hire cloud agents from the AgentSky catalog (included as ${CATALOG_FILE}) and coordinate them on one task. Use when: the person names an agent by @handle or wants to orchestrate agents; asks another engine (Codex, Claude Code, Gemini, Hermes) to do, test or review part of the work; wants to import, move or continue this conversation in AgentSky or the cloud; wants an agent their own application starts for its customers from a skill they supply; names a workspace; or the work splits into independent parts that can run at the same time. Works through the agentsky MCP server, or the sky command where those tools are missing."
65
+ ---
66
+
67
+ # Working with other agents through AgentSky
68
+
69
+ AgentSky runs long-lived agents in the cloud. You can hire them from its
70
+ catalog, give each a part of the work, and collect what they produce. Agents you
71
+ hire for the same piece of work share one task: a shared \`task/\` folder they all
72
+ read and write, listed as one task in the person's AgentSky account. You stay
73
+ responsible for the result.
74
+
75
+ Everything below is a tool of the \`agentsky\` MCP server. If those tools are
76
+ missing in this session, use the \`sky\` commands under "Without the MCP tools"
77
+ at the end; they do the same things, one agent at a time.
78
+
79
+ ## Getting access
80
+
81
+ If those tools are missing and \`sky auth whoami\` fails, this computer is not
82
+ signed in yet. Run \`npx -y @agentsky/sky@latest auth login --no-browser\`, give
83
+ the person the URL it prints, and wait: they approve once in their browser and
84
+ the command finishes by itself. Never ask them to paste a key or a password.
85
+
86
+ ## Workspace
87
+
88
+ Use the workspace the person named. If they named none, check the git root for
89
+ \`.agentsky.json\` \u2014 if it has a \`"workspace"\` key, use that. Otherwise use the
90
+ account default workspace. Never ask. Pass the chosen slug as \`workspace\` on
91
+ every MCP tool that accepts it, or as \`--workspace <slug>\` on sky commands.
92
+ Details: \`${REFERENCES_DIR}/workspaces.md\` in this skill's folder.
93
+
94
+ ## When to hire
95
+
96
+ - When the person names an agent (\`@handle\`) or an engine, or asks another agent
97
+ to test, review or do part of the work, do that. Do not substitute another one
98
+ silently.
99
+ - Otherwise hire for work another agent is better suited to than you are, for
100
+ independent parts that can run at the same time, or for work that should keep
101
+ going after this conversation ends.
102
+ - Do the work yourself when it is small, when it depends on what you already have
103
+ in front of you, or when explaining it would take as long as doing it.
104
+
105
+ ## Local first, cloud when it is not here, never a stand-in
106
+
107
+ - When the person names an engine that is installed and signed in on this
108
+ computer, run it here: it costs them nothing on AgentSky.
109
+ - When it is not installed here, start that same engine in the cloud: its handle
110
+ (\`@codex\`, \`@claude_code\`, \u2026) with \`start_session\` and a \`budget_cents\`, and say so
111
+ in one line ("Codex is not installed on this Mac, so it ran in the cloud").
112
+ Do not pick another engine instead.
113
+ - Every refused tool call carries a stable error \`code\` (in the error text and in
114
+ \`structuredContent.error\`) and, when there is one, a \`next_step\`. Read the code:
115
+ \`insufficient_credits\`, \`workspace_wallet_empty\` and \`payment_setup_required\` mean
116
+ the account cannot pay; \`budget_reached\` means that session's cap is spent.
117
+ Stop that piece of work and tell the person what was refused and what unblocks
118
+ it. When the refusal has \`tell_the_person\`, say that sentence as written: it holds
119
+ the link where they add credit. Retry the same request once they say it is done.
120
+ For a spent budget, name a larger \`budget_cents\`. Then offer the engines that are installed here as the free alternative. Never hire a
121
+ cheaper or different agent to get around a refusal.
122
+ - \`get_usage\` shows the balance; check it before starting several cloud sessions
123
+ at once so the person is told once, up front, instead of after the first fails.
124
+ - Anything else the person can do on agentsky.dev or in the Mac app (rename or
125
+ archive a thread, edit a Library file or skill, change an agent's model, invite
126
+ a member, \u2026) is an API operation: find it with \`search_api\`, read its
127
+ parameters with \`search_api\` given its method and path, and run it with \`call_api\`. It acts as the
128
+ person with their own key, so make only the change they asked for. The
129
+ workspace's files have their own tools: \`search_files\`, \`read_file\` and
130
+ \`write_file\`. Where MCP
131
+ is missing, \`sky api search <words>\` and \`sky api <METHOD> <path>\` do the same.
132
+
133
+ ## How to pick
134
+
135
+ Read \`${CATALOG_FILE}\` in this skill's folder. It lists every agent you can hire,
136
+ your own workspace's first, then by category: its \`@handle\`, its engine, what it
137
+ does and does not do, whether it can use MCP servers, and how it is paid. Pick by
138
+ the work, not by the name, and respect what an agent says it does not do.
139
+
140
+ Call \`search_catalog\` (with words for the work, or none to list everything)
141
+ when \`${CATALOG_FILE}\` is missing, when nothing in it fits, or when the person names
142
+ a handle it does not list: the catalog file is a snapshot from when the skill
143
+ was installed. If nothing fits, do the work yourself and say so.
144
+
145
+ ## How to brief
146
+
147
+ Start the first agent with \`start_session\`:
148
+
149
+ - \`agent_id\`: the handle, with its \`@\`.
150
+ - \`message\`: the brief.
151
+ - \`title\`: a short name for its part.
152
+ - \`budget_cents\`: the most it may spend, in US cents. Always set one. When it is
153
+ reached the agent pauses instead of spending more.
154
+ - \`idempotency_key\`: a new unique value for this hire. Reuse it only to retry
155
+ the exact same call after a timeout.
156
+
157
+ The agent cannot see this conversation or your files. A brief is one
158
+ self-contained paragraph that says:
159
+
160
+ 1. what to produce;
161
+ 2. where to write it: a path under \`task/<its part>/\`;
162
+ 3. what "done" means;
163
+ 4. anything it must not do.
164
+
165
+ Never put a password, key or token in a brief.
166
+
167
+ Its task id is the first session's id. Start every other agent for the same work
168
+ with that \`task_id\`, so it sees the same \`task/\` folder and the person sees one
169
+ task. To hand an agent a file, write it with \`write_session_shared_file\` before you brief
170
+ it, and name its path in the brief.
171
+
172
+ ## How to supervise
173
+
174
+ - Call \`read_session\` with the \`session_id\`, \`cursor\` and \`message_id\` that
175
+ \`start_session\` or \`send_message\` returned and \`wait_seconds: 50\`. Call again
176
+ with the returned cursor until \`turn_finished\` is true, and at once whenever
177
+ \`has_more\` is true. The first turn also boots the agent's sandbox, which can
178
+ take a minute.
179
+ - Run independent agents at the same time: start them all, then read each.
180
+ - To steer or answer an agent, \`send_message\` once its turn is finished.
181
+ - If \`get_session_status\` shows a request waiting on the person (a question, an approval,
182
+ or an app to connect with its link), show it to them and pass their answer with
183
+ \`answer_request\`. Never approve spending or access on their behalf.
184
+ - An agent that finishes its first turn with no reply did not start properly:
185
+ \`stop_session\` it and hire again, or do that part yourself.
186
+
187
+ ## How to finish
188
+
189
+ 1. \`collect_result\` for each agent: its last reply and the files it wrote.
190
+ 2. Read the files with \`read_session_shared_file\` and check each one exists and does what
191
+ was asked. An agent saying "done" is not evidence.
192
+ 3. Put the pieces together.
193
+ 4. If the person should be able to open or share the result, \`publish_artifact\`
194
+ the files; \`share_artifact\` only when they asked for a link. To change a
195
+ published file, \`save_artifact_file\` against the \`base_version\` you read;
196
+ \`update_artifact\` renames one and \`copy_artifact\` copies one version of it.
197
+ \`export_artifact\` hands a result over in any format its \`export_formats\`
198
+ lists, and \`import_artifact\` brings in a file or a public page as a result.
199
+ 5. Archive every agent you no longer need: \`stop_session\`, or \`call_api\`
200
+ \`POST /sessions/{id}/archive\` where your tool list has no \`stop_session\`.
201
+ 6. Tell the person what was done, which agent did which part, and what it cost
202
+ (\`get_session_status\` reports the task's cost).
203
+
204
+ ## Share an existing Library document
205
+
206
+ Use \`read_library_file_links\` with the document's exact \`ref\` to read its
207
+ current revision, supported access and real available members. The reference
208
+ can name a Drive file (including an uploaded meeting note), task file, memory
209
+ note, skill file, agent user instructions (\`{kind:"agent_prompt",agentId}\`), saved artifact or platform artifact. Only the user-authored AGENTS.md is shared; system instructions and credentials are never included. \`workspace\` names the
210
+ audience workspace, never a storage move or the connection's default.
211
+ For a DesignSystem file, use \`platform_artifact\` with the exact full native
212
+ manifest \`path\`: its actual \`root\` plus an \`editable_files\` path, or the
213
+ native document reader's \`libraryRef\`. Do not guess a folder prefix or use
214
+ an editor's relative transport path. Omitting \`path\` shares the entire
215
+ artifact entry. A token reads only its original file; it cannot select a
216
+ sibling with a query parameter. Editable DesignSystem files save through
217
+ that system's versioned writer, including derived files and republishing.
218
+ \`share_library_file\` changes only the requested workspace/member grants;
219
+ \`publish_library_file\` enables or disables a public view-only link while
220
+ preserving other grants. Both read first and merge against the current
221
+ revision. \`revoke_library_file_links\` needs the explicit revision you reviewed.
222
+ A conflict is an error: read the current state before intentionally retrying.
223
+ These tools send no messages and start no sessions. CLI equivalents are
224
+ \`sky library links show\`, \`share\`, \`publish\` and \`revoke\`; their help
225
+ shows every reference shape. Existing artifact links and version pins keep
226
+ using their existing controls and \`share_artifact\`.
227
+
228
+ When you receive a Library shared/public URL, \`read_shared_library_file\`
229
+ accepts the 43-character token at its end; \`public: true\` chooses the public
230
+ view-only reader. A recipient with a live edit grant can use
231
+ \`save_shared_library_file\` with the opaque source revision from that read
232
+ and exactly one native text/HTML/Office/restore field. Public links have no
233
+ writer. The CLI equivalents are \`sky library links read --token \u2026\`
234
+ (\`--output\` streams original bytes) and \`sky library links save --token \u2026
235
+ --revision \u2026 --file \u2026\`; \`--data\` accepts the other native save fields.
236
+ A 403 is not a saved result; a 409 requires reading current state before an
237
+ intentional retry. This source revision is distinct from the integer revision
238
+ of the sharing settings.
239
+
240
+ ## Build an agent that the person's own application runs
241
+
242
+ When the person wants an agent their product starts for its customers, built
243
+ from a skill they supply (for example: a customer uploads a file, an agent
244
+ reviews it, their application acts on the verdict), follow
245
+ \`${REFERENCES_DIR}/focused-agents.md\` in this skill's folder. It covers the
246
+ prerequisites to tell them about first, one locked-down workspace per customer,
247
+ one fresh session per event, and reading the answer as data.
248
+
249
+ ## Import this conversation to AgentSky
250
+
251
+ When the person asks to import, move, or continue this conversation in AgentSky
252
+ or the cloud:
253
+
254
+ 1. Write a summary JSON file following the schema in \`${REFERENCES_DIR}/import.md\`
255
+ (the only step that needs judgment \u2014 capture the objective, key decisions,
256
+ completed work, and next steps).
257
+ 2. Run:
258
+ \`\`\`
259
+ npx -y @agentsky/sky import --current --summary <path-to-summary.json> --yes --json
260
+ \`\`\`
261
+ Add \`--workspace <slug>\` when a workspace was chosen. Do NOT confirm or ask
262
+ before running; the \`--yes --json\` flags suppress prompts.
263
+ 3. Report the \`continueUrl\` from the JSON result. That is all.
264
+
265
+ Only stop (non-zero exit) on a size limit, dropped content, or redaction failure.
266
+
267
+ ## Without the MCP tools
268
+
269
+ Run \`sky auth whoami\`. If it says you are not logged in, ask the person to run
270
+ \`sky auth login\` and stop there. Never ask them for a token.
271
+
272
+ - Pick: \`sky catalog search <words for the work> --json\`. Each result has a
273
+ \`handle\`, what the agent does, its \`engine_type\`, its categories, how it is
274
+ paid, and what it needs. Run it with no words to see every agent.
275
+ - Brief: \`sky session create @<handle> --title "<short name>" --message "<brief>" --json\`
276
+ prints the new session's \`id\`. To give it a file, add \`--file <path>:/<name>\`:
277
+ the file is in the agent's working directory under that name, read-only, so
278
+ call it by that name in the brief.
279
+ - Collect: \`sky session read <session id> --wait --json\` waits until the agent
280
+ finishes its turn and prints its messages, with \`finished\` true or false. If
281
+ \`finished\` is false the wait timed out: run it again. To correct it, answer it
282
+ or ask for more, \`sky session message <session id> "<text>" --detach\`, then
283
+ read again.
284
+ `;
285
+ }
286
+ function importReferenceDoc() {
287
+ return `# Import this conversation to AgentSky
288
+
289
+ ## Summary schema (asteroids.session-summary v1)
290
+
291
+ Write a JSON file with these fields:
292
+
293
+ \`\`\`json
294
+ {
295
+ "format": "asteroids.session-summary",
296
+ "format_version": 1,
297
+ "source_harness": "claude_code",
298
+ "source_harness_version": null,
299
+ "source_session_id": "<the session id, e.g. from CLAUDE_CODE_SESSION_ID>",
300
+ "created_at": "<ISO 8601 timestamp>",
301
+ "summary": "<one paragraph: what this conversation accomplished>",
302
+ "context": {
303
+ "objective": "<what the person ultimately wants>",
304
+ "constraints": ["<must not do X>"],
305
+ "decisions": ["<decided to use Y approach>"],
306
+ "completed": ["<finished task A>"],
307
+ "pending": ["<next: do B>"],
308
+ "verification": ["<how to confirm B is correct>"],
309
+ "blockers": ["<needs access to X>"],
310
+ "artifacts": [{"path": "path/to/file.ts", "description": "what it is"}]
311
+ }
312
+ }
313
+ \`\`\`
314
+
315
+ Only \`summary\` and \`context\` require judgment. All other fields are fixed values
316
+ or can be omitted (the CLI validates \`format\` and \`format_version\`).
317
+
318
+ ## Gaps
319
+
320
+ The import transfers the recorded conversation only. These are NOT transferred:
321
+ - Local files not included in the transcript
322
+ - Runtime state (variables, shell state, running processes)
323
+ - Unrecorded tool outputs or reasoning
324
+ - Login credentials and secrets
325
+
326
+ List known gaps in \`context.blockers\`.
327
+
328
+ ## Non-Claude/Codex harnesses
329
+
330
+ For harnesses that do not set \`CLAUDE_CODE_SESSION_ID\` or \`CODEX_THREAD_ID\`:
331
+ use \`--session <id>\` instead of \`--current\`, and set \`source_harness\` to the
332
+ harness name (e.g. \`"hermes"\`, \`"openclaw"\`).
333
+ `;
334
+ }
335
+ function focusedAgentsReferenceDoc() {
336
+ return `# A focused agent your application runs for its customers
337
+
338
+ Use this when the person wants an agent that their own product starts on an
339
+ event (a customer uploads a file, a form is submitted), working from one
340
+ skill they supply, with the result going back to their application.
341
+
342
+ Everything here is the public API (\`https://api.agentsky.dev/v1\`). The
343
+ application's server calls it. The \`sky\` commands and MCP tools named
344
+ alongside do the same things by hand, for trying it out.
345
+
346
+ ## What has to exist first
347
+
348
+ Say each of these to the person before you build. Each one changes whether it
349
+ works:
350
+
351
+ - **An API key for their server.** They create it at
352
+ platform.agentsky.dev \u2192 Developer \u2192 API keys and put it in the server's
353
+ environment (\`AGENTSKY_TOKEN\`). Never put it in code, a page their customers
354
+ load, or a brief.
355
+ - **Credit** on their account. Every run is a session they pay for. Give each
356
+ one a budget.
357
+ - **The skill**: a directory with \`SKILL.md\` at its root.
358
+ - **An engine that fits.** Default to \`claude_code\` on its default model. Check
359
+ \`sky catalog search <words>\` if the skill needs something else.
360
+ - **Their own customer sign-in.** AgentSky does not know their customers. A
361
+ customer id their page sends is a label, not proof of who it is.
362
+
363
+ ## 1. One workspace per customer
364
+
365
+ \`\`\`
366
+ POST /v1/universes {"slug": "rv-acme", "name": "Uploads from acme"}
367
+ \`\`\`
368
+
369
+ Same by hand: \`sky universe create rv-acme\`. Files, memory, vaults and
370
+ sessions never cross workspaces. Name every later call's workspace with the
371
+ \`X-Universe: rv-acme\` header (\`--workspace rv-acme\` on \`sky\`).
372
+
373
+ ## 2. Lock the workspace down
374
+
375
+ \`\`\`
376
+ PUT /v1/hook_rules {"rules": [{"point": "tool.call", "action": "block", "match": {}, "enabled": true}]}
377
+ POST /v1/universes/rv-acme/policies {"name": "reviewer-native-tools", "kind": "TOOL_CALL",
378
+ "config": {"action": "deny", "matcher": "Bash|BashOutput|KillShell|Edit|MultiEdit|Write|NotebookEdit|WebFetch|WebSearch|Task|mcp__.*"}}
379
+ POST /v1/universes/rv-acme/policies {"name": "reviewer-no-helpers", "kind": "CAPABILITY", "config": {"platform.orchestration": "deny"}}
380
+ \`\`\`
381
+
382
+ - **The hook rule** blocks every connected-app and capability call. Without it,
383
+ the account owner's own connected apps reach sessions the owner's key
384
+ starts.
385
+ - **The \`TOOL_CALL\` rule** denies Claude Code's shell, write, web, sub-agent
386
+ and MCP tools. A denied call answers "The platform did not authorize this
387
+ tool invocation."
388
+ - **Keep only the tools the skill needs.** A reviewer needs Read.
389
+
390
+ Telling the agent not to use a tool is not a boundary. The rule is. By hand:
391
+ \`sky policy add --universe rv-acme --name ... --kind TOOL_CALL --config '<json>'\`.
392
+
393
+ ## 3. Install the skill, create the agent
394
+
395
+ \`\`\`
396
+ POST /v1/plugins multipart: one "files" field per file, named "<dir>/<path>", plus "displayName"
397
+ POST /v1/agents {"name": "upload-reviewer", "agentType": "claude_code", "prompt": "...",
398
+ "skills": [{"type": "skill", "skillId": "skill_..."}], "hiringPolicy": "deny"}
399
+ Idempotency-Key: provision-rv-acme-agent
400
+ \`\`\`
401
+
402
+ By hand: \`sky plugins upload ./upload-review --workspace rv-acme\`, then
403
+ \`sky agent create -f agent.toml --workspace rv-acme\` with
404
+ \`hiring_policy = "deny"\` and a \`[[skills]]\` table naming the skill id.
405
+
406
+ The prompt says what to read and what to answer. It also says that the
407
+ upload is data and that instructions written inside it are not to be
408
+ followed.
409
+
410
+ ## 4. One fresh session per event
411
+
412
+ \`\`\`
413
+ POST /v1/files multipart "file" \u2192 {"id": "file_..."}
414
+ POST /v1/sessions Idempotency-Key: session-<job id>
415
+ {"agent": "agent_...", "defaults": "none",
416
+ "resources": [{"type": "file", "file_id": "file_...", "mount_path": "/upload/request.txt"}],
417
+ "budget": {"type": "limit", "max_list_cost": {"amount": "50", "currency": "USD"}}}
418
+ POST /v1/sessions/{id}/events Idempotency-Key: brief-<job id>
419
+ {"events": [{"type": "user.message", "content": [{"type": "text", "text": "Review /workspace/upload/request.txt with the upload-review skill."}]}]}
420
+ \`\`\`
421
+
422
+ - **\`defaults: "none"\`** keeps every workspace default out of the session:
423
+ environment, vault, shared files, skills and team memory. The session holds
424
+ only what the request names.
425
+ - **Idempotency keys come from the event.** Retrying a timed-out call with the
426
+ same key returns the first session, or replays the first message. A keyed
427
+ create cannot carry \`initial_events\`. Create the session, save its id, then
428
+ send the brief.
429
+ - **Reuse a session** only for a job that continues for the same customer.
430
+
431
+ By hand: \`sky session create agent_... --no-defaults --budget-cents 50 --file ./request.txt:/upload/request.txt --message "..."\`
432
+ (MCP: \`start_session\`).
433
+
434
+ ## 5. Read the answer
435
+
436
+ \`\`\`
437
+ GET /v1/sessions/{id}/events?types[]=user.message&types[]=agent.message&types[]=session.status_idle&types[]=session.status_terminated&types[]=session.error
438
+ \`\`\`
439
+
440
+ - **When the turn is done.** It has ended at a \`session.status_idle\` whose
441
+ \`stop_reason.type\` is not \`requires_action\`, or at
442
+ \`session.status_terminated\`.
443
+ - **Where the answer is.** Take the last \`agent.message\` after the last
444
+ \`user.message\`. Earlier messages can be notes the agent wrote on the way.
445
+ - **Treat it as untrusted data.** Parse it against a fixed schema and fail
446
+ closed on anything else. Never run what it says.
447
+ - **Errors.** A \`session.error\` (budget reached, engine unavailable) is a
448
+ failure to report, not an answer.
449
+
450
+ By hand: \`sky session read <id> --wait --json\` (MCP: \`read_session\`).
451
+
452
+ ## 6. Questions and approvals
453
+
454
+ \`GET /v1/sessions/{session id}/status\` lists the requests waiting on the key's owner:
455
+ the agent's questions, approvals, and apps to connect.
456
+ \`POST /v1/sessions/{id}/questions/{request id}/answer\` with \`{"text": ...}\` or
457
+ \`{"option_id": ...}\` answers one. Pass a customer's answer on only after
458
+ your application has checked who they are. By hand: \`sky session status <id>\` and
459
+ \`sky session answer <id> <request> --text "..."\` (MCP: \`get_session_status\`,
460
+ \`answer_request\`).
461
+
462
+ ## 7. What the application keeps
463
+
464
+ The agent decides; the application acts. Keep these in the application's own
465
+ database:
466
+
467
+ - **One job per event**, with a unique event key. The same key with the same
468
+ payload returns the job it made; with a different payload it is a conflict.
469
+ - **The session id**, saved before you start polling, so a restart picks the
470
+ job up where it was.
471
+ - **A confirmation receipt** from the signed-in customer before any side
472
+ effect.
473
+ - **A unique action key per job**, so the side effect happens once. Agent
474
+ retries do not make it happen once; the key does.
475
+ - **Webhooks to the customer** with an event id, retried until acknowledged.
476
+
477
+ ## Before launch
478
+
479
+ Check one real session:
480
+
481
+ - \`GET /v1/sessions/{id}\` lists only the upload under \`resources\`.
482
+ - \`GET /v1/hook_rules\` and \`GET /v1/universes/{slug}/policies\` show the rules
483
+ above.
484
+ - Ask the agent directly to run a shell command. The answer has to be the
485
+ platform's refusal.
486
+ - A file id from another customer's workspace is refused at session create.
487
+ `;
488
+ }
489
+ function workspacesReferenceDoc() {
490
+ return `# Workspaces in AgentSky
491
+
492
+ A workspace (also called a universe) groups agents and sessions. Every API call
493
+ and MCP tool accepts an optional workspace slug.
494
+
495
+ ## How to choose
496
+
497
+ 1. The person named one \u2192 use it.
498
+ 2. Check the git root for \`.agentsky.json\` with a \`"workspace"\` key \u2192 use that.
499
+ 3. Neither \u2192 use the account default (personal workspace). Never ask.
500
+
501
+ ## Applying it
502
+
503
+ - MCP tools: pass \`workspace: "<slug>"\` on tools that accept it.
504
+ - sky CLI: \`--workspace <slug>\` on any command, or set \`SKY_WORKSPACE=<slug>\`.
505
+ - Tools that take a \`task_id\` or \`session_id\` inherit that task's workspace
506
+ automatically; one task never spans workspaces.
507
+
508
+ ## Listing workspaces
509
+
510
+ \`sky workspace list\` (or \`sky universe list\`) prints your workspaces, with
511
+ \`*\` marking the current default.
512
+
513
+ ## .agentsky.json
514
+
515
+ To set a per-repo default, create \`.agentsky.json\` at the git root:
516
+
517
+ \`\`\`json
518
+ {"workspace": "my-team-slug"}
519
+ \`\`\`
520
+ `;
521
+ }
522
+ function installedVersion(dir) {
523
+ try {
524
+ const marker = JSON.parse(readFileSync(join(dir, SKILL_MARKER), "utf8"));
525
+ return typeof marker.version === "string" ? marker.version : null;
526
+ } catch {
527
+ return null;
528
+ }
529
+ }
530
+ function skillState(agent) {
531
+ const version = installedVersion(join(agent.skillsDir, SKILL_NAME));
532
+ return version === null ? "missing" : version === CLI_VERSION ? "current" : "behind";
533
+ }
534
+ function isInstalledSkill(dir) {
535
+ return installedVersion(dir) !== null;
536
+ }
537
+ function installSkill(agent, opts = {}) {
538
+ const dir = join(agent.skillsDir, SKILL_NAME);
539
+ const previous = installedVersion(dir);
540
+ const outcome = previous === CLI_VERSION ? "current" : previous ? "updated" : "installed";
541
+ if (opts.dryRun) return { agent: agent.id, path: dir, outcome };
542
+ if (outcome !== "current") {
543
+ mkdirSync(dir, { recursive: true });
544
+ writeFileSync(join(dir, "SKILL.md"), skillDocument());
545
+ writeFileSync(join(dir, SKILL_MARKER), `${JSON.stringify({ version: CLI_VERSION }, null, 2)}
546
+ `);
547
+ }
548
+ if (opts.catalog) {
549
+ const catalog = renderCatalog(opts.catalog, opts.now ?? /* @__PURE__ */ new Date());
550
+ if (withoutDate(readOrNull(join(dir, CATALOG_FILE))) !== withoutDate(catalog)) {
551
+ mkdirSync(dir, { recursive: true });
552
+ writeFileSync(join(dir, CATALOG_FILE), catalog);
553
+ }
554
+ }
555
+ mkdirSync(join(dir, REFERENCES_DIR), { recursive: true });
556
+ for (const [path, content] of Object.entries(skillReferenceFiles())) writeFileSync(join(dir, path), content);
557
+ return { agent: agent.id, path: dir, outcome };
558
+ }
559
+ function readOrNull(path) {
560
+ try {
561
+ return readFileSync(path, "utf8");
562
+ } catch {
563
+ return null;
564
+ }
565
+ }
566
+ var withoutDate = (catalog) => catalog?.replace(/, as of \S+\./, ".") ?? null;
567
+ function skillPaths() {
568
+ return ["SKILL.md", SKILL_MARKER, CATALOG_FILE, ...Object.keys(skillReferenceFiles())];
569
+ }
570
+ function skillReferenceFiles() {
571
+ return {
572
+ [`${REFERENCES_DIR}/import.md`]: importReferenceDoc(),
573
+ [`${REFERENCES_DIR}/workspaces.md`]: workspacesReferenceDoc(),
574
+ [`${REFERENCES_DIR}/focused-agents.md`]: focusedAgentsReferenceDoc()
575
+ };
576
+ }
577
+
578
+ export {
579
+ SKILL_NAME,
580
+ SKILL_MARKER,
581
+ skillState,
582
+ isInstalledSkill,
583
+ installSkill,
584
+ skillPaths
585
+ };