@fungi.computer/oyster 0.57.0 → 0.57.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,5 +10,5 @@ export declare const platformSkillFiles: readonly [{
10
10
  readonly content: "---\nname: fungible-computing\ndescription:\n Change how you work on this Agent's Computer. Edit your standing instructions\n and voice, add a skill of your own, or replace a built-in skill. Use when\n asked to remember a rule for every conversation, change your tone, or teach\n yourself a repeatable task, or install a missing Computer toolchain or agent\n CLI.\n---\n\n# Fungible computing\n\nYour standing instructions and your skills are files on a Computer. You and your\nowner can both change them.\n\n## Computer tools\n\nOn a hosted Fungi Computer, if go, rust or an agent CLI is missing, run\n`fungi-tools install <tool>` through that Computer's exec operation. Select\n`go`, `rust` (for rustc and cargo), `claude`, `codex`, `opencode` or `pi`. Go\nand Rust persist in that Computer's home. Agent CLIs live in a cache that is\ncleared when the Computer sleeps; after a wake their first use reinstalls the\nsame pinned version and prints `installing <tool> (one-time after wake)`. A\nfailed install is an error to report, not a reason to fetch an unpinned\ninstaller. This command does not supply provider keys or sign the CLI in.\nMember-attached machines use their own installed tools.\n\n## Instructions and voice\n\n- `AGENTS.md` on Home holds standing instructions. `SYSTEM.md` on Home holds\n your voice. Both are read at the start of each run, so an edit applies from\n the next run.\n- Together the two files may hold 32,000 bytes. A file over the limit is not\n loaded.\n- Follow them unless they conflict with the instructions the host gave you\n first. They never grant a tool, an approval or access.\n- Your Home prompt section names where they are; read and edit them there.\n- Only a person changes Home, with `/home <name>`. Ask them when no Home is\n available.\n\n## Skills\n\n- A skill is a folder holding a `SKILL.md`. Put your own at\n `.agents/skills/<name>/SKILL.md` on a Computer.\n `.fungi/skills/<name>/SKILL.md` works too and is searched first.\n- `SKILL.md` starts with YAML frontmatter that has a `description`. The `name`\n should match the folder and use lowercase letters, digits and single hyphens,\n at most 64 characters. The prompt shows at most 512 characters of the\n description.\n- Load a skill inside `execute` with\n `return await skill.load({ name: \"skill-name\" });`. Add `file`, relative to\n the returned `baseDirectory`, for a supporting file in the folder.\n- A person can list every skill, and the file each came from, with `/skills`.\n\n## Replace a built-in skill\n\nBuilt-in skills ship with Fungi and are not files on a Computer. To replace one,\nmake a skill with the same name on a Computer, for example\n`.agents/skills/debug-fungi/SKILL.md`. The first skill found with a name wins,\nand a Computer's skills are searched before the built-in ones. Yours is listed,\nand `skill.load` returns yours. Discovery records that yours won.\n";
11
11
  }, {
12
12
  readonly path: "setup-fungi/SKILL.md";
13
- readonly content: "---\nname: setup-fungi\ndescription:\n Set yourself up for a new person in your first conversation, or when asked to\n set up Fungi or a project. Interview briefly, then do the setup yourself with\n their approval.\n---\n\n# Set up Fungi for your person\n\n## Goal\n\nWithin a few minutes, be set up for what they actually want: your instructions\nwritten, their project read, and, only if they want it, one App or one schedule.\nFinish with one useful result and the completed name and widget offers.\n\nSetup is one flow: approved work → useful result → name card → widget approval →\nfinish. After the work or a name answer, continue with the next tool call in the\nsame turn. A progress summary is commentary, never the end of setup. End only\nafter step 5 is complete, or while a card is parked awaiting its answer; when\nthat answer arrives, resume at the next unfinished item.\n\n## Start and resume\n\nOn resume, continue at the first unfinished step. A name answer goes straight to\nstep 5's rename/Keep handling, before file discovery or goal calls. The\ndiscovery and arming below happen once, at the start of setup.\n\nFirst list Home's working folder with its `list` tool (`{path: \".\"}`), or your\nattached Computer's `files.list({path: \".\"})`. Read `AGENTS.md` only if that\nlisting contains it, using `path: \"AGENTS.md\"`. Use that same relative path for\nedits; the working folder is not the filesystem root. If the file is absent,\ncontinue the interview and check again in step 3.\n\nBefore approved work, arm the existing Session goal so an accidental end of turn\nresumes this checklist without a nudge. Describe `goal`, read\n`env.goal.get_goal({})`, and, only when no goal is current, call\n`env.goal.create_goal({objective: \"Finish setting up for you, including your first useful result, a name card and widget approvals.\"})`.\nKeep an existing goal; never replace or complete someone else's objective for\nsetup. Save this goal's objective in setup progress so resumed turns reuse it.\nIf goal tools are absent, continue the checklist directly.\n\nA parked question or approval is a real wait; the goal runtime waits with it.\nAfter the useful result, use a declarative transition such as \"Your image is\nready.\" and make the name-card tool call in step 5 in this same turn. Put the\nentire name question and its options inside that card. A goal continuation\nrepairs an interrupted checklist; it never turns a plain-text name question into\na valid offer. On continuation, use step 5's resume check and call the missing\ncard directly or continue after its answer. Complete the setup goal only after\nstep 5's offers and cleanup have finished; keep it active while any required\noffer is pending.\n\n## Rules\n\n- Plain words. Say Agent, Computer, App, skill, schedule, Team or Home only at\n the moment you use that thing, with a one-sentence explanation.\n- One new concept per message. Name what you did, never list features.\n- Ask at most 3 cards in total, counting the \"Do it?\" plan and the name offer. A\n card is one `question.ask`; keep each short and specific, and batch a few\n questions into one card. Use options, the recommended one first. Free text is\n always allowed, and an option that lets them type their own answer is fine. Do\n not ask for the person's own name; their account already has it.\n- Every decision is a `question.ask` card, including \"Do it?\". Never end a turn\n asking the person to reply with options in text.\n- Propose, then act. Before writing files, cloning, scheduling or opening an\n App, show the `plan` checklist and ask \"Do it?\" with `question.ask` (options\n \"Do it\", \"Change something\", \"Skip\"). Reading needs no approval.\n- Document only what you observe. Every command, path and fact comes from a file\n you read or a command you ran.\n- Suggest only these Apps: Grove, Prints, Inkcap, Bazaar.\n- Skip any step whose tool this host does not give you, and carry on.\n- A build, install or test that fails or times out never ends setup: say what\n failed in one line, carry on, and still make every offer in step 5. A command\n result of `unknown` means it may still be running, so check again before\n calling it failed.\n- Media budget: at most ONE sample attempt across images and videos for the\n entire setup, including resumed turns. Make it only when the catalog/quote\n shows it is cheap and the approved plan includes it; otherwise save a useful\n prompt or brief as the first result. A failed, denied or expired generation\n spends that attempt. Never retry, switch models, or try the other medium. Say\n the cause once in plain words, then continue to the name and widget steps.\n- When they want to get on with a task, do the task and set up afterwards.\n- Keep prices and credit amounts out of your messages. Only the `setup.finish`\n line in step 5 mentions continuing.\n\n## Steps\n\n1. Understand. Open with one line that acknowledges what they just said. Then\n learn, from that message and at most 1 follow-up card: what they want Fungi\n for; whether there is a project (repo, folder, site, docs); anything that\n repeats (daily, weekly). Done when you can state their goal in a sentence.\n2. Plan. Write a `plan` checklist of at most 4 items, each one concrete thing\n you will do. Ask \"Do it?\". Done when they answer.\n3. Do, item by item, ticking the plan.\n - Instructions. List the working folder again with `files.list({path: \".\"})`.\n When `AGENTS.md` is listed, read and edit `path: \"AGENTS.md\"` in place;\n when it is not there yet, your Computer is still finishing its first start:\n carry on with the other items, come back to it before step 4, and if it is\n still missing create it with the same headings. Fill its \"About my person\"\n section (rename it \"About <their name>\") with their goal, the preferences\n they stated and how they want updates. Follow its \"Keeping this file up to\n date\" section from then on. Every line answers \"would I get this wrong\n without it?\". Then introduce instructions in one sentence: \"I saved this in\n my instructions, so I'll remember it in every conversation. You can read or\n edit them from my menu → Instructions.\"\n - Files you create for them: write several in one `files.patch` of Add File\n blocks rather than one write each, so they approve once. Write files with\n `files.patch` or `files.write`, never shell heredocs inside `execute`,\n whose quoting breaks.\n - Project, if any. Get it onto your Computer.\n - A public repo: `git clone` into `/workspace/<repo>`.\n - A private GitHub repo, when the `gitTeam` tool is present: first offer\n \"Connect GitHub\" as a link to the GitHub connector in Team settings. Once\n the repo is granted, run `gitTeam.clone` into `/workspace/<repo>`.\n - Files: ask them to drop the files in Inkcap.\n\n Then crawl it: list the top level; read the README, manifests and\n lockfiles; the build, test, lint and CI config; existing rule files\n (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.cursorrules`,\n `.github/copilot-instructions.md`); then a few representative source files.\n Write or improve the project's own `AGENTS.md` with exact commands\n (including one test), entry points, boundaries and gotchas. Show the 3 most\n useful lines you learned. Introduce your Computer in one sentence: \"I have\n my own Computer, a private machine where I keep files and run things.\"\n\n - Repeating work, if any. Propose one schedule with a time and time zone.\n Create it from a new conversation named for the job.\n - An App, only when a stated need matches one. Offer its App link.\n - Prints: apply the Media budget above before calling\n `PRINTS.generateImage` or `PRINTS.generateVideo`. Record the attempt in\n Home's setup progress before calling, so a resumed turn cannot repeat it.\n Mark a keeper with `PRINTS.setFavorite` on its saved path and read them\n back with `PRINTS.listFavorites`. The library folder is chosen by the\n person in Prints, and no method lets you choose it, so do not search for\n one: if Prints says no library is selected, say so in one line and tell\n them to pick it in Prints.\n4. First result. Do one small real task toward their goal, now. When they can\n see its output, immediately enter step 5 in this turn. If media is\n unavailable, a saved prompt or brief is the result; the media budget still\n applies.\n5. Finish. Do every item below, in order. Do not end your turn before the name\n offer and the dashboard offer have each been asked, failed, or skipped. Even\n if part of setup is blocked, such as an App that is not ready, say so in your\n two lines and still make both offers. An answered card is final: do not ask\n it again in text.\n - Say in two lines what you set up and where to change it, then continue\n immediately to the name card tool call.\n - Resume check. Read your current name from your instructions, the answers\n and rename results already in this conversation, and Home's setup progress.\n If a name was picked (including Keep), or a rename already succeeded, the\n name is settled: skip the name card and rename call and proceed directly to\n widgets. A current name different from the starting name saved in setup\n progress also proves the rename happened. If a name card is still pending,\n wait on that same card instead of issuing a replacement. Plain text and an\n offered marker alone do not prove a card is waiting: without an actual name\n card call in this conversation, make that call now. A nudge, failure or\n interrupted turn resumes this checklist; it never restarts setup.\n - Offer a name, once (required). Never settle it yourself by saying you keep\n your name: the card is how they keep it. Before the first name card, save\n its offered status and your starting name under \"First conversation\" in\n Home `AGENTS.md`. Ask with `question.ask`: \"Keep <your name>\" first, where\n your name is the one in your instructions (\"Your name is …\"), copied\n verbatim and never guessed, then two names you suggest that fit their goal;\n free text is always allowed. In `execute`, bind `currentName` to that\n verbatim current name and choose `firstSuggestion` and `secondSuggestion`,\n then run the actual card call below. Your chat transition is a statement;\n the name question belongs inside this call:\n\n ```js\n return await env.question.ask({\n questions: [\n {\n id: \"agent_name\",\n header: \"Name\",\n question: \"Choose a name for me\",\n options: [\n {\n label: `Keep ${currentName}`,\n description: \"Keep my current name.\",\n },\n { label: firstSuggestion, description: \"Use this name.\" },\n { label: secondSuggestion, description: \"Use this name.\" },\n ],\n },\n ],\n });\n ```\n\n Ask the name only as a `question.ask` card, never in plain text. Wait for\n their pick: call `question.ask` without `mode`, never `mode: \"continue\"`,\n and make no dashboard call until they have picked. Ask it at most once in\n the whole conversation, even if you run step 5 again. Once they have\n picked, whether a new name or Keep, the name is settled: never ask it\n again, not even after an empty or interrupted turn; carry on with the\n dashboard offer. Only when they pick a new name, call\n `await env.self.rename({name})`: the moment they pick a new name, your very\n next call is `await env.self.rename({name})`, before any other step. Then\n say in one line that you are now called that. Call it directly and do not\n look it up first, since a lookup of a tool you may not see reads as absent.\n If `env.self` is missing or the call is refused, say nothing about it.\n After applying their pick, save the settled name (including Keep) in setup\n progress, then immediately call `await env.TOURTOIS.widgets.available({})`\n in this turn.\n\n - Offer \"Add to your dashboard\" (required). Call\n `await env.TOURTOIS.widgets.available({})` and pick at most 2 matching\n widgets from what you did: Grove Inbox, Inkcap Recent Files, Prints Recent\n Outputs. If no widget clearly matches what you did, offer the most\n generally useful one: Inbox first, then Recent Files. Skip the offer only\n when `widgets.available` returns nothing but the launcher. Never say there\n is no dashboard offer before you have called\n `await env.TOURTOIS.widgets.available({})`. Do not use `question.ask` here.\n For each widget, write one plain line first, such as \"I'm adding Inbox to\n your dashboard; approve the card if you want it.\", then call\n `await env.TOURTOIS.layout.get({})` and\n `await env.TOURTOIS.layout.place({ ... })` with its `surfaceId`, `gillId`,\n a size the widget lists, `scope` \"member\" and `basedOn` the revision\n `layout.get` returned. The call makes the Hub show the person an approval\n card to Approve or Deny. The approval card is their choice: wait for it.\n Denied or expired means move on: do not retry or ask again. Pass `params`\n only for the keys the widget lists, with values you know, and pass every\n key the widget lists as required in `params`, for example\n `params: { computer: <id> }`. Never call `layout.place` without them: a\n call missing one is rejected after the person has approved it. When a\n required parameter is a Computer and the Team has exactly one, use the id\n from your instructions:\n `params: { computer: <the id from your instructions> }`. Skip a widget\n whose required Computer you cannot fill because the Team has none, or more\n than one. Skip a widget only when a required parameter has no value you can\n fill. Never ask a yes or no question before `layout.place`: if a widget\n needs something the person must do first, say so in one line and skip that\n widget. Never place one without that approval, and never add one for a\n person who denied. If `env.TOURTOIS` is missing or a call fails, skip it.\n - Delete the \"First conversation\" section from Home `AGENTS.md`.\n - When the `setup.finish` tool is available, say one more line: \"That's you\n set up. To keep going with me, start Pro, or link your wallet if you're a\n holder.\" Then call `setup.finish()` once in your final `execute`. If you\n created the setup goal, that same invocation must first await\n `env.goal.update_goal({status: \"complete\", reason: \"Useful result delivered; name and widget offers settled; setup progress cleaned up.\"})`,\n then await `env.setup.finish({})`. Keep the two calls together so the\n hand-off cannot leave the setup goal unfinished. Leave any other current\n goal alone.\n - When the `setup.finish` tool is absent, finish after the offers and cleanup\n above are complete. If you created the setup goal, your final tool call is\n `await env.goal.update_goal({status: \"complete\", reason: \"Useful result delivered; name and widget offers settled; setup progress cleaned up.\"})`.\n Leave any other current goal alone. That host has no money step; say\n nothing about Pro or wallets. Its absence never skips the name card or\n widget approval.\n\n## Credit\n\n- When the `setup.finish` description says less than $0.15 of credit remains,\n finish the step in hand, then do step 5 without starting a crawl.\n- Reach step 5 only after the first useful result. A hand-off before that leaves\n the person with nothing.\n";
13
+ readonly content: "---\nname: setup-fungi\ndescription:\n Set yourself up for a new person in your first conversation, or when asked to\n set up Fungi or a project. Interview briefly, then do the setup yourself with\n their approval.\n---\n\n# Set up Fungi for your person\n\n## Goal\n\nWithin a few minutes, be set up for what they actually want: your instructions\nwritten, their project read, and, only if they want it, one App or one schedule.\nFinish with one useful result and the completed name and widget offers.\n\nSetup is one flow: approved work → useful result → name card → widget approval →\nfinish. After the work or a name answer, continue with the next tool call in the\nsame turn. A progress summary is commentary, never the end of setup. End only\nafter step 5 is complete, or while a card is parked awaiting its answer; when\nthat answer arrives, resume at the next unfinished item.\n\n## Start and resume\n\nOn resume, continue at the first unfinished step. A name answer goes straight to\nstep 5's rename/Keep handling, before file discovery or goal calls. The\ndiscovery and arming below happen once, at the start of setup.\n\nFirst list Home's working folder with its `list` tool (`{path: \".\"}`), or your\nattached Computer's `files.list({path: \".\"})`. Read `AGENTS.md` only if that\nlisting contains it, using `path: \"AGENTS.md\"`. Use that same relative path for\nedits; the working folder is not the filesystem root. An absent `AGENTS.md` is\nnot read: the listing already checked whether it exists. Continue to goal arming\nand the interview; create it only in approved step 3.\n\nBefore approved work, arm the existing Session goal so an accidental end of turn\nresumes this checklist without a nudge. Describe `goal`, read\n`env.goal.get_goal({})`, and, only when no goal is current, call\n`env.goal.create_goal({objective: \"Finish setting up for you, including your first useful result, a name card and widget approvals.\"})`.\nKeep an existing goal; never replace or complete someone else's objective for\nsetup. Record a setup goal you created in step 3's progress after approval.\nUntil then, reuse it from this conversation; arming is complete after the goal\ncall. If goal tools are absent, continue the checklist directly.\n\nA parked question or approval is a real wait; the goal runtime waits with it.\nAfter the useful result, use a declarative transition such as \"Your image is\nready.\" and make the name-card tool call in step 5 in this same turn. Put the\nentire name question and its options inside that card. A goal continuation\nrepairs an interrupted checklist; it never turns a plain-text name question into\na valid offer. On continuation, use step 5's resume check and call the missing\ncard directly or continue after its answer. Complete the setup goal only after\nstep 5's offers and cleanup have finished; keep it active while any required\noffer is pending.\n\n## Rules\n\n- Plain words. Say Agent, Computer, App, skill, schedule, Team or Home only at\n the moment you use that thing, with a one-sentence explanation.\n- One new concept per message. Name what you did, never list features.\n- Ask at most 3 cards in total, counting the \"Do it?\" plan and the name offer. A\n card is one `question.ask`; keep each short and specific, and batch a few\n questions into one card. Use options, the recommended one first. Free text is\n always allowed, and an option that lets them type their own answer is fine. Do\n not ask for the person's own name; their account already has it.\n- Every decision is a `question.ask` card, including \"Do it?\". Never end a turn\n asking the person to reply with options in text.\n- Propose, then act. Before writing files, cloning, scheduling or opening an\n App, show the `plan` checklist and ask \"Do it?\" with `question.ask` (options\n \"Do it\", \"Change something\", \"Skip\"). Reading needs no approval.\n- Document only what you observe. Every command, path and fact comes from a file\n you read or a command you ran.\n- Suggest only these Apps: Grove, Prints, Inkcap, Bazaar.\n- Skip any step whose tool this host does not give you, and carry on.\n- A build, install or test that fails or times out never ends setup: say what\n failed in one line, carry on, and still make every offer in step 5. A command\n result of `unknown` means it may still be running, so check again before\n calling it failed.\n- Media budget: at most ONE sample attempt across images and videos for the\n entire setup, including resumed turns. Make it only when the catalog/quote\n shows it is cheap and the approved plan includes it; otherwise save a useful\n prompt or brief as the first result. A failed, denied or expired generation\n spends that attempt. Never retry, switch models, or try the other medium. Say\n the cause once in plain words, then continue to the name and widget steps.\n- When they want to get on with a task, do the task and set up afterwards.\n- Keep prices and credit amounts out of your messages. Only the `setup.finish`\n line in step 5 mentions continuing.\n\n## Steps\n\n1. Understand. Open with one line that acknowledges what they just said. Then\n learn, from that message and at most 1 follow-up card: what they want Fungi\n for; whether there is a project (repo, folder, site, docs); anything that\n repeats (daily, weekly). Done when you can state their goal in a sentence.\n2. Plan. Write a `plan` checklist of at most 4 items, each one concrete thing\n you will do. Ask \"Do it?\". Done when they answer.\n3. Do, item by item, ticking the plan.\n\n For files on Home, group several in one direct `apply_patch` tool call with\n Add File blocks and Home-relative paths. Send the patch as tool data, keeping\n HTML, JavaScript backticks and `${...}` out of JavaScript source strings.\n This is a direct tool call, outside `execute`; never shell heredocs inside\n `execute`. If this tool is unavailable, say file writing is blocked and\n continue to the offers in step 5.\n\n - Instructions. List the working folder again with `files.list({path: \".\"})`.\n When `AGENTS.md` is listed, read and edit `path: \"AGENTS.md\"` in place;\n when absent, create it now with the starter headings \"About my person\",\n \"Keeping this file up to date\" and temporary \"First conversation\" progress.\n Record any owned setup goal objective in that progress. Fill its \"About my\n person\" section (rename it \"About <their name>\") with their goal, the\n preferences they stated and how they want updates. Follow its \"Keeping this\n file up to date\" section from then on. Every line answers \"would I get this\n wrong without it?\". Then introduce instructions in one sentence: \"I saved\n this in my instructions, so I'll remember it in every conversation. You can\n read or edit them from my menu → Instructions.\"\n - Project, if any. Get it onto your Computer.\n - A public repo: `git clone` into `/workspace/<repo>`.\n - A private GitHub repo, when the `gitTeam` tool is present: first offer\n \"Connect GitHub\" as a link to the GitHub connector in Team settings. Once\n the repo is granted, run `gitTeam.clone` into `/workspace/<repo>`.\n - Files: ask them to drop the files in Inkcap.\n\n Then crawl it: list the top level; read the README, manifests and\n lockfiles; the build, test, lint and CI config; existing rule files\n (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.cursorrules`,\n `.github/copilot-instructions.md`); then a few representative source files.\n Write or improve the project's own `AGENTS.md` with exact commands\n (including one test), entry points, boundaries and gotchas. Show the 3 most\n useful lines you learned. Introduce your Computer in one sentence: \"I have\n my own Computer, a private machine where I keep files and run things.\"\n\n - Repeating work, if any. Propose one schedule with a time and time zone.\n Create it from a new conversation named for the job.\n - An App, only when a stated need matches one. Offer its App link.\n - Prints: apply the Media budget above before calling\n `PRINTS.generateImage` or `PRINTS.generateVideo`. Record the attempt in\n Home's setup progress before calling, so a resumed turn cannot repeat it.\n Mark a keeper with `PRINTS.setFavorite` on its saved path and read them\n back with `PRINTS.listFavorites`. The library folder is chosen by the\n person in Prints, and no method lets you choose it, so do not search for\n one: if Prints says no library is selected, say so in one line and tell\n them to pick it in Prints.\n\n4. First result. Do one small real task toward their goal, now. When they can\n see its output, immediately enter step 5 in this turn. If media is\n unavailable, a saved prompt or brief is the result; the media budget still\n applies.\n5. Finish. Do every item below, in order. Do not end your turn before the name\n offer and the dashboard offer have each been asked, failed, or skipped. Even\n if part of setup is blocked, such as an App that is not ready, say so in your\n two lines and still make both offers. An answered card is final: do not ask\n it again in text.\n - Say in two lines what you set up and where to change it, then continue\n immediately to the name card tool call.\n - Resume check. Read your current name from your instructions, the answers\n and rename results already in this conversation, and Home's setup progress.\n If a name was picked (including Keep), or a rename already succeeded, the\n name is settled: skip the name card and rename call and proceed directly to\n widgets. A current name different from the starting name saved in setup\n progress also proves the rename happened. If a name card is still pending,\n wait on that same card instead of issuing a replacement. Plain text and an\n offered marker alone do not prove a card is waiting: without an actual name\n card call in this conversation, make that call now. A nudge, failure or\n interrupted turn resumes this checklist; it never restarts setup.\n - Offer a name, once (required). Never settle it yourself by saying you keep\n your name: the card is how they keep it. Before the first name card, save\n its offered status and your starting name under \"First conversation\" in\n Home `AGENTS.md`. Ask with `question.ask`: \"Keep <your name>\" first, where\n your name is the one in your instructions (\"Your name is …\"), copied\n verbatim and never guessed, then two names you suggest that fit their goal;\n free text is always allowed. In `execute`, bind `currentName` to that\n verbatim current name and choose `firstSuggestion` and `secondSuggestion`,\n then run the actual card call below. Your chat transition is a statement;\n the name question belongs inside this call:\n\n ```js\n return await env.question.ask({\n questions: [\n {\n id: \"agent_name\",\n header: \"Name\",\n question: \"Choose a name for me\",\n options: [\n {\n label: `Keep ${currentName}`,\n description: \"Keep my current name.\",\n },\n { label: firstSuggestion, description: \"Use this name.\" },\n { label: secondSuggestion, description: \"Use this name.\" },\n ],\n },\n ],\n });\n ```\n\n Ask the name only as a `question.ask` card, never in plain text. Wait for\n their pick: call `question.ask` without `mode`, never `mode: \"continue\"`,\n and make no dashboard call until they have picked. Ask it at most once in\n the whole conversation, even if you run step 5 again. Once they have\n picked, whether a new name or Keep, the name is settled: never ask it\n again, not even after an empty or interrupted turn; carry on with the\n dashboard offer. Only when they pick a new name, call\n `await env.self.rename({name})`: the moment they pick a new name, your very\n next call is `await env.self.rename({name})`, before any other step. Then\n say in one line that you are now called that. Call it directly and do not\n look it up first, since a lookup of a tool you may not see reads as absent.\n If `env.self` is missing or the call is refused, say nothing about it.\n After applying their pick, save the settled name (including Keep) in setup\n progress, then immediately call `await env.TOURTOIS.widgets.available({})`\n in this turn.\n\n - Offer \"Add to your dashboard\" (required). Call\n `await env.TOURTOIS.widgets.available({})` and pick at most 2 matching\n widgets from what you did: Grove Inbox, Inkcap Recent Files, Prints Recent\n Outputs. If no widget clearly matches what you did, offer the most\n generally useful one: Inbox first, then Recent Files. Skip the offer only\n when `widgets.available` returns nothing but the launcher. Never say there\n is no dashboard offer before you have called\n `await env.TOURTOIS.widgets.available({})`. Do not use `question.ask` here.\n For each widget, write one plain line first, such as \"I'm adding Inbox to\n your dashboard; approve the card if you want it.\", then call\n `await env.TOURTOIS.layout.get({})` and\n `await env.TOURTOIS.layout.place({ ... })` with its `surfaceId`, `gillId`,\n a size the widget lists, `scope` \"member\" and `basedOn` the revision\n `layout.get` returned. The call makes the Hub show the person an approval\n card to Approve or Deny. The approval card is their choice: wait for it.\n Denied or expired means move on: do not retry or ask again. Pass `params`\n only for the keys the widget lists, with values you know, and pass every\n key the widget lists as required in `params`, for example\n `params: { computer: <id> }`. Never call `layout.place` without them: a\n call missing one is rejected after the person has approved it. When a\n required parameter is a Computer and the Team has exactly one, use the id\n from your instructions:\n `params: { computer: <the id from your instructions> }`. Skip a widget\n whose required Computer you cannot fill because the Team has none, or more\n than one. Skip a widget only when a required parameter has no value you can\n fill. Never ask a yes or no question before `layout.place`: if a widget\n needs something the person must do first, say so in one line and skip that\n widget. Never place one without that approval, and never add one for a\n person who denied. If `env.TOURTOIS` is missing or a call fails, skip it.\n - Delete the \"First conversation\" section from Home `AGENTS.md`.\n - When the `setup.finish` tool is available, say one more line: \"That's you\n set up. To keep going with me, start Pro, or link your wallet if you're a\n holder.\" Then call `setup.finish()` once in your final `execute`. If you\n created the setup goal, that same invocation must first await\n `env.goal.update_goal({status: \"complete\", reason: \"Useful result delivered; name and widget offers settled; setup progress cleaned up.\"})`,\n then await `env.setup.finish({})`. Keep the two calls together so the\n hand-off cannot leave the setup goal unfinished. Leave any other current\n goal alone.\n - When the `setup.finish` tool is absent, finish after the offers and cleanup\n above are complete. If you created the setup goal, your final tool call is\n `await env.goal.update_goal({status: \"complete\", reason: \"Useful result delivered; name and widget offers settled; setup progress cleaned up.\"})`.\n Leave any other current goal alone. That host has no money step; say\n nothing about Pro or wallets. Its absence never skips the name card or\n widget approval.\n\n## Credit\n\n- When the `setup.finish` description says less than $0.15 of credit remains,\n finish the step in hand, then do step 5 without starting a crawl.\n- Reach step 5 only after the first useful result. A hand-off before that leaves\n the person with nothing.\n";
14
14
  }];
@@ -15,6 +15,6 @@ export const platformSkillFiles = [
15
15
  },
16
16
  {
17
17
  path: "setup-fungi/SKILL.md",
18
- content: '---\nname: setup-fungi\ndescription:\n Set yourself up for a new person in your first conversation, or when asked to\n set up Fungi or a project. Interview briefly, then do the setup yourself with\n their approval.\n---\n\n# Set up Fungi for your person\n\n## Goal\n\nWithin a few minutes, be set up for what they actually want: your instructions\nwritten, their project read, and, only if they want it, one App or one schedule.\nFinish with one useful result and the completed name and widget offers.\n\nSetup is one flow: approved work → useful result → name card → widget approval →\nfinish. After the work or a name answer, continue with the next tool call in the\nsame turn. A progress summary is commentary, never the end of setup. End only\nafter step 5 is complete, or while a card is parked awaiting its answer; when\nthat answer arrives, resume at the next unfinished item.\n\n## Start and resume\n\nOn resume, continue at the first unfinished step. A name answer goes straight to\nstep 5\'s rename/Keep handling, before file discovery or goal calls. The\ndiscovery and arming below happen once, at the start of setup.\n\nFirst list Home\'s working folder with its `list` tool (`{path: "."}`), or your\nattached Computer\'s `files.list({path: "."})`. Read `AGENTS.md` only if that\nlisting contains it, using `path: "AGENTS.md"`. Use that same relative path for\nedits; the working folder is not the filesystem root. If the file is absent,\ncontinue the interview and check again in step 3.\n\nBefore approved work, arm the existing Session goal so an accidental end of turn\nresumes this checklist without a nudge. Describe `goal`, read\n`env.goal.get_goal({})`, and, only when no goal is current, call\n`env.goal.create_goal({objective: "Finish setting up for you, including your first useful result, a name card and widget approvals."})`.\nKeep an existing goal; never replace or complete someone else\'s objective for\nsetup. Save this goal\'s objective in setup progress so resumed turns reuse it.\nIf goal tools are absent, continue the checklist directly.\n\nA parked question or approval is a real wait; the goal runtime waits with it.\nAfter the useful result, use a declarative transition such as "Your image is\nready." and make the name-card tool call in step 5 in this same turn. Put the\nentire name question and its options inside that card. A goal continuation\nrepairs an interrupted checklist; it never turns a plain-text name question into\na valid offer. On continuation, use step 5\'s resume check and call the missing\ncard directly or continue after its answer. Complete the setup goal only after\nstep 5\'s offers and cleanup have finished; keep it active while any required\noffer is pending.\n\n## Rules\n\n- Plain words. Say Agent, Computer, App, skill, schedule, Team or Home only at\n the moment you use that thing, with a one-sentence explanation.\n- One new concept per message. Name what you did, never list features.\n- Ask at most 3 cards in total, counting the "Do it?" plan and the name offer. A\n card is one `question.ask`; keep each short and specific, and batch a few\n questions into one card. Use options, the recommended one first. Free text is\n always allowed, and an option that lets them type their own answer is fine. Do\n not ask for the person\'s own name; their account already has it.\n- Every decision is a `question.ask` card, including "Do it?". Never end a turn\n asking the person to reply with options in text.\n- Propose, then act. Before writing files, cloning, scheduling or opening an\n App, show the `plan` checklist and ask "Do it?" with `question.ask` (options\n "Do it", "Change something", "Skip"). Reading needs no approval.\n- Document only what you observe. Every command, path and fact comes from a file\n you read or a command you ran.\n- Suggest only these Apps: Grove, Prints, Inkcap, Bazaar.\n- Skip any step whose tool this host does not give you, and carry on.\n- A build, install or test that fails or times out never ends setup: say what\n failed in one line, carry on, and still make every offer in step 5. A command\n result of `unknown` means it may still be running, so check again before\n calling it failed.\n- Media budget: at most ONE sample attempt across images and videos for the\n entire setup, including resumed turns. Make it only when the catalog/quote\n shows it is cheap and the approved plan includes it; otherwise save a useful\n prompt or brief as the first result. A failed, denied or expired generation\n spends that attempt. Never retry, switch models, or try the other medium. Say\n the cause once in plain words, then continue to the name and widget steps.\n- When they want to get on with a task, do the task and set up afterwards.\n- Keep prices and credit amounts out of your messages. Only the `setup.finish`\n line in step 5 mentions continuing.\n\n## Steps\n\n1. Understand. Open with one line that acknowledges what they just said. Then\n learn, from that message and at most 1 follow-up card: what they want Fungi\n for; whether there is a project (repo, folder, site, docs); anything that\n repeats (daily, weekly). Done when you can state their goal in a sentence.\n2. Plan. Write a `plan` checklist of at most 4 items, each one concrete thing\n you will do. Ask "Do it?". Done when they answer.\n3. Do, item by item, ticking the plan.\n - Instructions. List the working folder again with `files.list({path: "."})`.\n When `AGENTS.md` is listed, read and edit `path: "AGENTS.md"` in place;\n when it is not there yet, your Computer is still finishing its first start:\n carry on with the other items, come back to it before step 4, and if it is\n still missing create it with the same headings. Fill its "About my person"\n section (rename it "About <their name>") with their goal, the preferences\n they stated and how they want updates. Follow its "Keeping this file up to\n date" section from then on. Every line answers "would I get this wrong\n without it?". Then introduce instructions in one sentence: "I saved this in\n my instructions, so I\'ll remember it in every conversation. You can read or\n edit them from my menu → Instructions."\n - Files you create for them: write several in one `files.patch` of Add File\n blocks rather than one write each, so they approve once. Write files with\n `files.patch` or `files.write`, never shell heredocs inside `execute`,\n whose quoting breaks.\n - Project, if any. Get it onto your Computer.\n - A public repo: `git clone` into `/workspace/<repo>`.\n - A private GitHub repo, when the `gitTeam` tool is present: first offer\n "Connect GitHub" as a link to the GitHub connector in Team settings. Once\n the repo is granted, run `gitTeam.clone` into `/workspace/<repo>`.\n - Files: ask them to drop the files in Inkcap.\n\n Then crawl it: list the top level; read the README, manifests and\n lockfiles; the build, test, lint and CI config; existing rule files\n (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.cursorrules`,\n `.github/copilot-instructions.md`); then a few representative source files.\n Write or improve the project\'s own `AGENTS.md` with exact commands\n (including one test), entry points, boundaries and gotchas. Show the 3 most\n useful lines you learned. Introduce your Computer in one sentence: "I have\n my own Computer, a private machine where I keep files and run things."\n\n - Repeating work, if any. Propose one schedule with a time and time zone.\n Create it from a new conversation named for the job.\n - An App, only when a stated need matches one. Offer its App link.\n - Prints: apply the Media budget above before calling\n `PRINTS.generateImage` or `PRINTS.generateVideo`. Record the attempt in\n Home\'s setup progress before calling, so a resumed turn cannot repeat it.\n Mark a keeper with `PRINTS.setFavorite` on its saved path and read them\n back with `PRINTS.listFavorites`. The library folder is chosen by the\n person in Prints, and no method lets you choose it, so do not search for\n one: if Prints says no library is selected, say so in one line and tell\n them to pick it in Prints.\n4. First result. Do one small real task toward their goal, now. When they can\n see its output, immediately enter step 5 in this turn. If media is\n unavailable, a saved prompt or brief is the result; the media budget still\n applies.\n5. Finish. Do every item below, in order. Do not end your turn before the name\n offer and the dashboard offer have each been asked, failed, or skipped. Even\n if part of setup is blocked, such as an App that is not ready, say so in your\n two lines and still make both offers. An answered card is final: do not ask\n it again in text.\n - Say in two lines what you set up and where to change it, then continue\n immediately to the name card tool call.\n - Resume check. Read your current name from your instructions, the answers\n and rename results already in this conversation, and Home\'s setup progress.\n If a name was picked (including Keep), or a rename already succeeded, the\n name is settled: skip the name card and rename call and proceed directly to\n widgets. A current name different from the starting name saved in setup\n progress also proves the rename happened. If a name card is still pending,\n wait on that same card instead of issuing a replacement. Plain text and an\n offered marker alone do not prove a card is waiting: without an actual name\n card call in this conversation, make that call now. A nudge, failure or\n interrupted turn resumes this checklist; it never restarts setup.\n - Offer a name, once (required). Never settle it yourself by saying you keep\n your name: the card is how they keep it. Before the first name card, save\n its offered status and your starting name under "First conversation" in\n Home `AGENTS.md`. Ask with `question.ask`: "Keep <your name>" first, where\n your name is the one in your instructions ("Your name is …"), copied\n verbatim and never guessed, then two names you suggest that fit their goal;\n free text is always allowed. In `execute`, bind `currentName` to that\n verbatim current name and choose `firstSuggestion` and `secondSuggestion`,\n then run the actual card call below. Your chat transition is a statement;\n the name question belongs inside this call:\n\n ```js\n return await env.question.ask({\n questions: [\n {\n id: "agent_name",\n header: "Name",\n question: "Choose a name for me",\n options: [\n {\n label: `Keep ${currentName}`,\n description: "Keep my current name.",\n },\n { label: firstSuggestion, description: "Use this name." },\n { label: secondSuggestion, description: "Use this name." },\n ],\n },\n ],\n });\n ```\n\n Ask the name only as a `question.ask` card, never in plain text. Wait for\n their pick: call `question.ask` without `mode`, never `mode: "continue"`,\n and make no dashboard call until they have picked. Ask it at most once in\n the whole conversation, even if you run step 5 again. Once they have\n picked, whether a new name or Keep, the name is settled: never ask it\n again, not even after an empty or interrupted turn; carry on with the\n dashboard offer. Only when they pick a new name, call\n `await env.self.rename({name})`: the moment they pick a new name, your very\n next call is `await env.self.rename({name})`, before any other step. Then\n say in one line that you are now called that. Call it directly and do not\n look it up first, since a lookup of a tool you may not see reads as absent.\n If `env.self` is missing or the call is refused, say nothing about it.\n After applying their pick, save the settled name (including Keep) in setup\n progress, then immediately call `await env.TOURTOIS.widgets.available({})`\n in this turn.\n\n - Offer "Add to your dashboard" (required). Call\n `await env.TOURTOIS.widgets.available({})` and pick at most 2 matching\n widgets from what you did: Grove Inbox, Inkcap Recent Files, Prints Recent\n Outputs. If no widget clearly matches what you did, offer the most\n generally useful one: Inbox first, then Recent Files. Skip the offer only\n when `widgets.available` returns nothing but the launcher. Never say there\n is no dashboard offer before you have called\n `await env.TOURTOIS.widgets.available({})`. Do not use `question.ask` here.\n For each widget, write one plain line first, such as "I\'m adding Inbox to\n your dashboard; approve the card if you want it.", then call\n `await env.TOURTOIS.layout.get({})` and\n `await env.TOURTOIS.layout.place({ ... })` with its `surfaceId`, `gillId`,\n a size the widget lists, `scope` "member" and `basedOn` the revision\n `layout.get` returned. The call makes the Hub show the person an approval\n card to Approve or Deny. The approval card is their choice: wait for it.\n Denied or expired means move on: do not retry or ask again. Pass `params`\n only for the keys the widget lists, with values you know, and pass every\n key the widget lists as required in `params`, for example\n `params: { computer: <id> }`. Never call `layout.place` without them: a\n call missing one is rejected after the person has approved it. When a\n required parameter is a Computer and the Team has exactly one, use the id\n from your instructions:\n `params: { computer: <the id from your instructions> }`. Skip a widget\n whose required Computer you cannot fill because the Team has none, or more\n than one. Skip a widget only when a required parameter has no value you can\n fill. Never ask a yes or no question before `layout.place`: if a widget\n needs something the person must do first, say so in one line and skip that\n widget. Never place one without that approval, and never add one for a\n person who denied. If `env.TOURTOIS` is missing or a call fails, skip it.\n - Delete the "First conversation" section from Home `AGENTS.md`.\n - When the `setup.finish` tool is available, say one more line: "That\'s you\n set up. To keep going with me, start Pro, or link your wallet if you\'re a\n holder." Then call `setup.finish()` once in your final `execute`. If you\n created the setup goal, that same invocation must first await\n `env.goal.update_goal({status: "complete", reason: "Useful result delivered; name and widget offers settled; setup progress cleaned up."})`,\n then await `env.setup.finish({})`. Keep the two calls together so the\n hand-off cannot leave the setup goal unfinished. Leave any other current\n goal alone.\n - When the `setup.finish` tool is absent, finish after the offers and cleanup\n above are complete. If you created the setup goal, your final tool call is\n `await env.goal.update_goal({status: "complete", reason: "Useful result delivered; name and widget offers settled; setup progress cleaned up."})`.\n Leave any other current goal alone. That host has no money step; say\n nothing about Pro or wallets. Its absence never skips the name card or\n widget approval.\n\n## Credit\n\n- When the `setup.finish` description says less than $0.15 of credit remains,\n finish the step in hand, then do step 5 without starting a crawl.\n- Reach step 5 only after the first useful result. A hand-off before that leaves\n the person with nothing.\n',
18
+ content: '---\nname: setup-fungi\ndescription:\n Set yourself up for a new person in your first conversation, or when asked to\n set up Fungi or a project. Interview briefly, then do the setup yourself with\n their approval.\n---\n\n# Set up Fungi for your person\n\n## Goal\n\nWithin a few minutes, be set up for what they actually want: your instructions\nwritten, their project read, and, only if they want it, one App or one schedule.\nFinish with one useful result and the completed name and widget offers.\n\nSetup is one flow: approved work → useful result → name card → widget approval →\nfinish. After the work or a name answer, continue with the next tool call in the\nsame turn. A progress summary is commentary, never the end of setup. End only\nafter step 5 is complete, or while a card is parked awaiting its answer; when\nthat answer arrives, resume at the next unfinished item.\n\n## Start and resume\n\nOn resume, continue at the first unfinished step. A name answer goes straight to\nstep 5\'s rename/Keep handling, before file discovery or goal calls. The\ndiscovery and arming below happen once, at the start of setup.\n\nFirst list Home\'s working folder with its `list` tool (`{path: "."}`), or your\nattached Computer\'s `files.list({path: "."})`. Read `AGENTS.md` only if that\nlisting contains it, using `path: "AGENTS.md"`. Use that same relative path for\nedits; the working folder is not the filesystem root. An absent `AGENTS.md` is\nnot read: the listing already checked whether it exists. Continue to goal arming\nand the interview; create it only in approved step 3.\n\nBefore approved work, arm the existing Session goal so an accidental end of turn\nresumes this checklist without a nudge. Describe `goal`, read\n`env.goal.get_goal({})`, and, only when no goal is current, call\n`env.goal.create_goal({objective: "Finish setting up for you, including your first useful result, a name card and widget approvals."})`.\nKeep an existing goal; never replace or complete someone else\'s objective for\nsetup. Record a setup goal you created in step 3\'s progress after approval.\nUntil then, reuse it from this conversation; arming is complete after the goal\ncall. If goal tools are absent, continue the checklist directly.\n\nA parked question or approval is a real wait; the goal runtime waits with it.\nAfter the useful result, use a declarative transition such as "Your image is\nready." and make the name-card tool call in step 5 in this same turn. Put the\nentire name question and its options inside that card. A goal continuation\nrepairs an interrupted checklist; it never turns a plain-text name question into\na valid offer. On continuation, use step 5\'s resume check and call the missing\ncard directly or continue after its answer. Complete the setup goal only after\nstep 5\'s offers and cleanup have finished; keep it active while any required\noffer is pending.\n\n## Rules\n\n- Plain words. Say Agent, Computer, App, skill, schedule, Team or Home only at\n the moment you use that thing, with a one-sentence explanation.\n- One new concept per message. Name what you did, never list features.\n- Ask at most 3 cards in total, counting the "Do it?" plan and the name offer. A\n card is one `question.ask`; keep each short and specific, and batch a few\n questions into one card. Use options, the recommended one first. Free text is\n always allowed, and an option that lets them type their own answer is fine. Do\n not ask for the person\'s own name; their account already has it.\n- Every decision is a `question.ask` card, including "Do it?". Never end a turn\n asking the person to reply with options in text.\n- Propose, then act. Before writing files, cloning, scheduling or opening an\n App, show the `plan` checklist and ask "Do it?" with `question.ask` (options\n "Do it", "Change something", "Skip"). Reading needs no approval.\n- Document only what you observe. Every command, path and fact comes from a file\n you read or a command you ran.\n- Suggest only these Apps: Grove, Prints, Inkcap, Bazaar.\n- Skip any step whose tool this host does not give you, and carry on.\n- A build, install or test that fails or times out never ends setup: say what\n failed in one line, carry on, and still make every offer in step 5. A command\n result of `unknown` means it may still be running, so check again before\n calling it failed.\n- Media budget: at most ONE sample attempt across images and videos for the\n entire setup, including resumed turns. Make it only when the catalog/quote\n shows it is cheap and the approved plan includes it; otherwise save a useful\n prompt or brief as the first result. A failed, denied or expired generation\n spends that attempt. Never retry, switch models, or try the other medium. Say\n the cause once in plain words, then continue to the name and widget steps.\n- When they want to get on with a task, do the task and set up afterwards.\n- Keep prices and credit amounts out of your messages. Only the `setup.finish`\n line in step 5 mentions continuing.\n\n## Steps\n\n1. Understand. Open with one line that acknowledges what they just said. Then\n learn, from that message and at most 1 follow-up card: what they want Fungi\n for; whether there is a project (repo, folder, site, docs); anything that\n repeats (daily, weekly). Done when you can state their goal in a sentence.\n2. Plan. Write a `plan` checklist of at most 4 items, each one concrete thing\n you will do. Ask "Do it?". Done when they answer.\n3. Do, item by item, ticking the plan.\n\n For files on Home, group several in one direct `apply_patch` tool call with\n Add File blocks and Home-relative paths. Send the patch as tool data, keeping\n HTML, JavaScript backticks and `${...}` out of JavaScript source strings.\n This is a direct tool call, outside `execute`; never shell heredocs inside\n `execute`. If this tool is unavailable, say file writing is blocked and\n continue to the offers in step 5.\n\n - Instructions. List the working folder again with `files.list({path: "."})`.\n When `AGENTS.md` is listed, read and edit `path: "AGENTS.md"` in place;\n when absent, create it now with the starter headings "About my person",\n "Keeping this file up to date" and temporary "First conversation" progress.\n Record any owned setup goal objective in that progress. Fill its "About my\n person" section (rename it "About <their name>") with their goal, the\n preferences they stated and how they want updates. Follow its "Keeping this\n file up to date" section from then on. Every line answers "would I get this\n wrong without it?". Then introduce instructions in one sentence: "I saved\n this in my instructions, so I\'ll remember it in every conversation. You can\n read or edit them from my menu → Instructions."\n - Project, if any. Get it onto your Computer.\n - A public repo: `git clone` into `/workspace/<repo>`.\n - A private GitHub repo, when the `gitTeam` tool is present: first offer\n "Connect GitHub" as a link to the GitHub connector in Team settings. Once\n the repo is granted, run `gitTeam.clone` into `/workspace/<repo>`.\n - Files: ask them to drop the files in Inkcap.\n\n Then crawl it: list the top level; read the README, manifests and\n lockfiles; the build, test, lint and CI config; existing rule files\n (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.cursorrules`,\n `.github/copilot-instructions.md`); then a few representative source files.\n Write or improve the project\'s own `AGENTS.md` with exact commands\n (including one test), entry points, boundaries and gotchas. Show the 3 most\n useful lines you learned. Introduce your Computer in one sentence: "I have\n my own Computer, a private machine where I keep files and run things."\n\n - Repeating work, if any. Propose one schedule with a time and time zone.\n Create it from a new conversation named for the job.\n - An App, only when a stated need matches one. Offer its App link.\n - Prints: apply the Media budget above before calling\n `PRINTS.generateImage` or `PRINTS.generateVideo`. Record the attempt in\n Home\'s setup progress before calling, so a resumed turn cannot repeat it.\n Mark a keeper with `PRINTS.setFavorite` on its saved path and read them\n back with `PRINTS.listFavorites`. The library folder is chosen by the\n person in Prints, and no method lets you choose it, so do not search for\n one: if Prints says no library is selected, say so in one line and tell\n them to pick it in Prints.\n\n4. First result. Do one small real task toward their goal, now. When they can\n see its output, immediately enter step 5 in this turn. If media is\n unavailable, a saved prompt or brief is the result; the media budget still\n applies.\n5. Finish. Do every item below, in order. Do not end your turn before the name\n offer and the dashboard offer have each been asked, failed, or skipped. Even\n if part of setup is blocked, such as an App that is not ready, say so in your\n two lines and still make both offers. An answered card is final: do not ask\n it again in text.\n - Say in two lines what you set up and where to change it, then continue\n immediately to the name card tool call.\n - Resume check. Read your current name from your instructions, the answers\n and rename results already in this conversation, and Home\'s setup progress.\n If a name was picked (including Keep), or a rename already succeeded, the\n name is settled: skip the name card and rename call and proceed directly to\n widgets. A current name different from the starting name saved in setup\n progress also proves the rename happened. If a name card is still pending,\n wait on that same card instead of issuing a replacement. Plain text and an\n offered marker alone do not prove a card is waiting: without an actual name\n card call in this conversation, make that call now. A nudge, failure or\n interrupted turn resumes this checklist; it never restarts setup.\n - Offer a name, once (required). Never settle it yourself by saying you keep\n your name: the card is how they keep it. Before the first name card, save\n its offered status and your starting name under "First conversation" in\n Home `AGENTS.md`. Ask with `question.ask`: "Keep <your name>" first, where\n your name is the one in your instructions ("Your name is …"), copied\n verbatim and never guessed, then two names you suggest that fit their goal;\n free text is always allowed. In `execute`, bind `currentName` to that\n verbatim current name and choose `firstSuggestion` and `secondSuggestion`,\n then run the actual card call below. Your chat transition is a statement;\n the name question belongs inside this call:\n\n ```js\n return await env.question.ask({\n questions: [\n {\n id: "agent_name",\n header: "Name",\n question: "Choose a name for me",\n options: [\n {\n label: `Keep ${currentName}`,\n description: "Keep my current name.",\n },\n { label: firstSuggestion, description: "Use this name." },\n { label: secondSuggestion, description: "Use this name." },\n ],\n },\n ],\n });\n ```\n\n Ask the name only as a `question.ask` card, never in plain text. Wait for\n their pick: call `question.ask` without `mode`, never `mode: "continue"`,\n and make no dashboard call until they have picked. Ask it at most once in\n the whole conversation, even if you run step 5 again. Once they have\n picked, whether a new name or Keep, the name is settled: never ask it\n again, not even after an empty or interrupted turn; carry on with the\n dashboard offer. Only when they pick a new name, call\n `await env.self.rename({name})`: the moment they pick a new name, your very\n next call is `await env.self.rename({name})`, before any other step. Then\n say in one line that you are now called that. Call it directly and do not\n look it up first, since a lookup of a tool you may not see reads as absent.\n If `env.self` is missing or the call is refused, say nothing about it.\n After applying their pick, save the settled name (including Keep) in setup\n progress, then immediately call `await env.TOURTOIS.widgets.available({})`\n in this turn.\n\n - Offer "Add to your dashboard" (required). Call\n `await env.TOURTOIS.widgets.available({})` and pick at most 2 matching\n widgets from what you did: Grove Inbox, Inkcap Recent Files, Prints Recent\n Outputs. If no widget clearly matches what you did, offer the most\n generally useful one: Inbox first, then Recent Files. Skip the offer only\n when `widgets.available` returns nothing but the launcher. Never say there\n is no dashboard offer before you have called\n `await env.TOURTOIS.widgets.available({})`. Do not use `question.ask` here.\n For each widget, write one plain line first, such as "I\'m adding Inbox to\n your dashboard; approve the card if you want it.", then call\n `await env.TOURTOIS.layout.get({})` and\n `await env.TOURTOIS.layout.place({ ... })` with its `surfaceId`, `gillId`,\n a size the widget lists, `scope` "member" and `basedOn` the revision\n `layout.get` returned. The call makes the Hub show the person an approval\n card to Approve or Deny. The approval card is their choice: wait for it.\n Denied or expired means move on: do not retry or ask again. Pass `params`\n only for the keys the widget lists, with values you know, and pass every\n key the widget lists as required in `params`, for example\n `params: { computer: <id> }`. Never call `layout.place` without them: a\n call missing one is rejected after the person has approved it. When a\n required parameter is a Computer and the Team has exactly one, use the id\n from your instructions:\n `params: { computer: <the id from your instructions> }`. Skip a widget\n whose required Computer you cannot fill because the Team has none, or more\n than one. Skip a widget only when a required parameter has no value you can\n fill. Never ask a yes or no question before `layout.place`: if a widget\n needs something the person must do first, say so in one line and skip that\n widget. Never place one without that approval, and never add one for a\n person who denied. If `env.TOURTOIS` is missing or a call fails, skip it.\n - Delete the "First conversation" section from Home `AGENTS.md`.\n - When the `setup.finish` tool is available, say one more line: "That\'s you\n set up. To keep going with me, start Pro, or link your wallet if you\'re a\n holder." Then call `setup.finish()` once in your final `execute`. If you\n created the setup goal, that same invocation must first await\n `env.goal.update_goal({status: "complete", reason: "Useful result delivered; name and widget offers settled; setup progress cleaned up."})`,\n then await `env.setup.finish({})`. Keep the two calls together so the\n hand-off cannot leave the setup goal unfinished. Leave any other current\n goal alone.\n - When the `setup.finish` tool is absent, finish after the offers and cleanup\n above are complete. If you created the setup goal, your final tool call is\n `await env.goal.update_goal({status: "complete", reason: "Useful result delivered; name and widget offers settled; setup progress cleaned up."})`.\n Leave any other current goal alone. That host has no money step; say\n nothing about Pro or wallets. Its absence never skips the name card or\n widget approval.\n\n## Credit\n\n- When the `setup.finish` description says less than $0.15 of credit remains,\n finish the step in hand, then do step 5 without starting a crawl.\n- Reach step 5 only after the first useful result. A hand-off before that leaves\n the person with nothing.\n',
19
19
  },
20
20
  ];
@@ -0,0 +1,84 @@
1
+ import { z } from "zod";
2
+ export declare const portPreviewReferrerPolicy = "same-origin";
3
+ declare const issueRefusal: z.ZodEnum<{
4
+ owner_required: "owner_required";
5
+ app_not_allowed: "app_not_allowed";
6
+ preview_not_configured: "preview_not_configured";
7
+ invalid_computer_address: "invalid_computer_address";
8
+ unexposed: "unexposed";
9
+ capacity: "capacity";
10
+ }>;
11
+ export type PortPreviewIssueRefusal = z.infer<typeof issueRefusal>;
12
+ /** The Computer preserves the reason for refusing issuance across RPC. */
13
+ export declare const portPreviewIssueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
14
+ kind: z.ZodLiteral<"issued">;
15
+ previewUrl: z.ZodURL;
16
+ }, z.core.$strip>, z.ZodObject<{
17
+ kind: z.ZodLiteral<"refused">;
18
+ reason: z.ZodEnum<{
19
+ owner_required: "owner_required";
20
+ app_not_allowed: "app_not_allowed";
21
+ preview_not_configured: "preview_not_configured";
22
+ invalid_computer_address: "invalid_computer_address";
23
+ unexposed: "unexposed";
24
+ capacity: "capacity";
25
+ }>;
26
+ }, z.core.$strip>], "kind">;
27
+ export type PortPreviewIssue = z.infer<typeof portPreviewIssueSchema>;
28
+ declare const portPreviewRefusalSchema: z.ZodEnum<{
29
+ unavailable: "unavailable";
30
+ owner_required: "owner_required";
31
+ app_not_allowed: "app_not_allowed";
32
+ preview_not_configured: "preview_not_configured";
33
+ invalid_computer_address: "invalid_computer_address";
34
+ unexposed: "unexposed";
35
+ capacity: "capacity";
36
+ confirmation_required: "confirmation_required";
37
+ same_origin_required: "same_origin_required";
38
+ computer_not_found: "computer_not_found";
39
+ invalid_port: "invalid_port";
40
+ }>;
41
+ export type PortPreviewRefusal = z.infer<typeof portPreviewRefusalSchema>;
42
+ export declare function portPreviewRefusalMessage(reason: PortPreviewRefusal): string;
43
+ export declare const portPreviewRefusalStatus: {
44
+ readonly owner_required: 403;
45
+ readonly app_not_allowed: 403;
46
+ readonly preview_not_configured: 503;
47
+ readonly invalid_computer_address: 404;
48
+ readonly unexposed: 404;
49
+ readonly capacity: 429;
50
+ readonly confirmation_required: 403;
51
+ readonly same_origin_required: 403;
52
+ readonly computer_not_found: 404;
53
+ readonly invalid_port: 404;
54
+ readonly unavailable: 503;
55
+ };
56
+ /** Only route text and a closed refusal enter the browser's confirmation. */
57
+ export declare const portPreviewEntrySchema: z.ZodObject<{
58
+ port: z.ZodLazy<z.ZodNumber>;
59
+ action: z.ZodString;
60
+ computerId: z.ZodString;
61
+ refusal: z.ZodOptional<z.ZodEnum<{
62
+ unavailable: "unavailable";
63
+ owner_required: "owner_required";
64
+ app_not_allowed: "app_not_allowed";
65
+ preview_not_configured: "preview_not_configured";
66
+ invalid_computer_address: "invalid_computer_address";
67
+ unexposed: "unexposed";
68
+ capacity: "capacity";
69
+ confirmation_required: "confirmation_required";
70
+ same_origin_required: "same_origin_required";
71
+ computer_not_found: "computer_not_found";
72
+ invalid_port: "invalid_port";
73
+ }>>;
74
+ }, z.core.$strict>;
75
+ export type PortPreviewEntry = z.infer<typeof portPreviewEntrySchema>;
76
+ /** Entry routes use the contract's bounds and one canonical decimal spelling. */
77
+ export declare function parsePortPreviewPort(text: string): number | undefined;
78
+ /** Decode the owned POST refusal into the next confirmation's presentation. */
79
+ export declare function portPreviewRefusalEntry(response: Response, route: Readonly<{
80
+ action: string;
81
+ computerId: string;
82
+ port: string;
83
+ }>): Promise<PortPreviewEntry | undefined>;
84
+ export {};
@@ -0,0 +1,86 @@
1
+ import { z } from "zod";
2
+ import { computerPortInputSchema } from "@fungi.computer/computer-contract";
3
+ // no-referrer turns a native form's Origin into null. Keep confirmation
4
+ // provenance; the issued-ticket redirect separately uses no-referrer.
5
+ export const portPreviewReferrerPolicy = "same-origin";
6
+ const issueRefusal = z.enum([
7
+ "owner_required",
8
+ "app_not_allowed",
9
+ "preview_not_configured",
10
+ "invalid_computer_address",
11
+ "unexposed",
12
+ "capacity",
13
+ ]);
14
+ /** The Computer preserves the reason for refusing issuance across RPC. */
15
+ export const portPreviewIssueSchema = z.discriminatedUnion("kind", [
16
+ z.object({ kind: z.literal("issued"), previewUrl: z.url() }),
17
+ z.object({ kind: z.literal("refused"), reason: issueRefusal }),
18
+ ]);
19
+ const portPreviewRefusalSchema = z.enum([
20
+ ...issueRefusal.options,
21
+ "confirmation_required",
22
+ "same_origin_required",
23
+ "computer_not_found",
24
+ "invalid_port",
25
+ "unavailable",
26
+ ]);
27
+ const portPreviewRefusalResponseSchema = z.object({
28
+ error: portPreviewRefusalSchema,
29
+ });
30
+ const messages = {
31
+ owner_required: "Sign in as this Oyster's owner before opening the preview.",
32
+ app_not_allowed: "This App is no longer allowed to open this Computer's preview.",
33
+ preview_not_configured: "Private port previews aren't configured on this Oyster.",
34
+ invalid_computer_address: "This Computer's address cannot be used for a private preview.",
35
+ unexposed: "This port is no longer exposed. Expose it in Shed, then try again.",
36
+ capacity: "Too many preview links are waiting to open. Wait a few minutes, then try again.",
37
+ confirmation_required: "This request didn't include your confirmation. Choose Open preview in your Oyster.",
38
+ same_origin_required: "This preview request came from another site. Open it from your Oyster.",
39
+ computer_not_found: "That Computer doesn't belong to this Oyster.",
40
+ invalid_port: "That preview link doesn't contain a valid port number.",
41
+ unavailable: "The Computer couldn't create a preview right now. Try again.",
42
+ };
43
+ export function portPreviewRefusalMessage(reason) {
44
+ return messages[reason];
45
+ }
46
+ export const portPreviewRefusalStatus = {
47
+ owner_required: 403,
48
+ app_not_allowed: 403,
49
+ preview_not_configured: 503,
50
+ invalid_computer_address: 404,
51
+ unexposed: 404,
52
+ capacity: 429,
53
+ confirmation_required: 403,
54
+ same_origin_required: 403,
55
+ computer_not_found: 404,
56
+ invalid_port: 404,
57
+ unavailable: 503,
58
+ };
59
+ /** Only route text and a closed refusal enter the browser's confirmation. */
60
+ export const portPreviewEntrySchema = computerPortInputSchema.extend({
61
+ action: z.string(),
62
+ computerId: z.string(),
63
+ refusal: portPreviewRefusalSchema.optional(),
64
+ });
65
+ /** Entry routes use the contract's bounds and one canonical decimal spelling. */
66
+ export function parsePortPreviewPort(text) {
67
+ const parsed = computerPortInputSchema.safeParse({ port: Number(text) });
68
+ return parsed.success && String(parsed.data.port) === text
69
+ ? parsed.data.port
70
+ : undefined;
71
+ }
72
+ /** Decode the owned POST refusal into the next confirmation's presentation. */
73
+ export async function portPreviewRefusalEntry(response, route) {
74
+ const port = parsePortPreviewPort(route.port);
75
+ if (port === undefined)
76
+ return undefined;
77
+ let refusal = response.status === 401 || response.status === 403
78
+ ? "owner_required"
79
+ : "unavailable";
80
+ if (response.headers.get("Content-Type")?.startsWith("application/json")) {
81
+ const parsed = portPreviewRefusalResponseSchema.safeParse(await response.clone().json());
82
+ if (parsed.success)
83
+ refusal = parsed.data.error;
84
+ }
85
+ return { action: route.action, computerId: route.computerId, port, refusal };
86
+ }
@@ -1,3 +1,4 @@
1
+ import type { PortPreviewIssue } from "../port-preview-entry.js";
1
2
  import { type ComputerApiRequest } from "../computer-api.js";
2
3
  import { type ComputerSize } from "@fungi.computer/computer/backing";
3
4
  import { type AppMethodRefusedReply } from "@fungi.computer/agar/backend";
@@ -202,9 +203,7 @@ export declare class ComputerDO extends NativeComputerDO implements ComputerFetc
202
203
  }>>;
203
204
  /** List reusable owner entry URLs for every exposed port, or refuse typed. */
204
205
  portPreviews(authority: ComputerGrant, selectorInput: PreviewSelector): Promise<ComputerPortPreviewsReply>;
205
- issuePortConnect(ownerId: string, port: number): Promise<{
206
- previewUrl: string;
207
- } | null>;
206
+ issuePortConnect(ownerId: string, port: number): Promise<PortPreviewIssue>;
208
207
  portPreview(port: number, request: Request): Promise<Response>;
209
208
  /**
210
209
  * The host side of native execution (Computer ABI 0edb0e4a): the grant's
@@ -392,7 +392,7 @@ export class ComputerDO extends NativeComputerDO {
392
392
  async #previewInstallation(selector) {
393
393
  const owner = await (await standaloneTenancy(this.previewBindings)).owner();
394
394
  if (selector.ownerId !== owner?.actor.memberId)
395
- throw new PreviewRefused();
395
+ throw new PreviewRefused("owner_required");
396
396
  const current = await this.previewBindings.REGISTRY.getByName("registry").get(selector.installationId);
397
397
  if (current === null ||
398
398
  "kind" in current ||
@@ -400,14 +400,14 @@ export class ComputerDO extends NativeComputerDO {
400
400
  JSON.stringify(selectionOf(current)) !==
401
401
  JSON.stringify(selector.selection) ||
402
402
  current.release.artifact.artifactDigest !== selector.artifactDigest)
403
- throw new PreviewRefused();
403
+ throw new PreviewRefused("app_not_allowed");
404
404
  return current;
405
405
  }
406
406
  async #currentPreview(selector) {
407
407
  const current = await this.#previewInstallation(selector);
408
408
  const verified = await verifyRelease(r2ArtifactStore(this.previewBindings.RELEASES), current.release, undefined, false);
409
409
  if (!verified.declaration?.capabilities.includes("computer.execute"))
410
- throw new PreviewRefused();
410
+ throw new PreviewRefused("app_not_allowed");
411
411
  await this.#previewInstallation(selector);
412
412
  }
413
413
  async #previewOwner() {
@@ -415,7 +415,7 @@ export class ComputerDO extends NativeComputerDO {
415
415
  return this.#preview;
416
416
  const origins = await previewOrigins(this.previewBindings);
417
417
  if (origins === null)
418
- throw new PreviewRefused();
418
+ throw new PreviewRefused("preview_not_configured");
419
419
  await this.listPortsAfterAcceptance(() => undefined);
420
420
  this.#preview = createStandalonePreview(this.state.storage, this.#id(), origins, {
421
421
  accept: (ownerId) => {
@@ -486,7 +486,7 @@ export class ComputerDO extends NativeComputerDO {
486
486
  async #portPreviews(authority, selectorInput) {
487
487
  const selector = Schema.decodeUnknownSync(previewSelectorSchema)(selectorInput);
488
488
  if (authority.provenance.actor !== `owner:${selector.ownerId}`)
489
- throw new PreviewRefused();
489
+ throw new PreviewRefused("app_not_allowed");
490
490
  this.#accept(authority, "listPorts");
491
491
  await this.#currentPreview(selector);
492
492
  const ports = await this.listPortsAfterAcceptance(() => {
@@ -505,13 +505,17 @@ export class ComputerDO extends NativeComputerDO {
505
505
  async issuePortConnect(ownerId, port) {
506
506
  const owner = await (await standaloneTenancy(this.previewBindings)).owner();
507
507
  if (owner?.actor.memberId !== ownerId)
508
- return null;
508
+ return { kind: "refused", reason: "owner_required" };
509
509
  try {
510
- return await (await this.#previewOwner()).issueOwner(ownerId, port);
510
+ const issued = await (await this.#previewOwner()).issueOwner(ownerId, port);
511
+ return { kind: "issued", previewUrl: issued.previewUrl };
511
512
  }
512
513
  catch (cause) {
513
- if (cause instanceof PreviewRefused || cause instanceof PortAccessError)
514
- return null;
514
+ if (cause instanceof PreviewRefused)
515
+ return { kind: "refused", reason: cause.reason };
516
+ if (cause instanceof PortAccessError &&
517
+ (cause.reason === "unexposed" || cause.reason === "capacity"))
518
+ return { kind: "refused", reason: cause.reason };
515
519
  throw cause;
516
520
  }
517
521
  }
@@ -1,6 +1,7 @@
1
1
  import * as Schema from "effect/Schema";
2
2
  import { ComputerPortAccess } from "@fungi.computer/computer/port-access";
3
3
  import type { OysterEnv } from "../host.js";
4
+ import { type PortPreviewIssue, type PortPreviewIssueRefusal } from "../port-preview-entry.js";
4
5
  export declare const previewSelectorSchema: Schema.Struct<{
5
6
  readonly ownerId: Schema.NonEmptyString;
6
7
  readonly installationId: Schema.NonEmptyString;
@@ -30,6 +31,8 @@ export type StandalonePreviewEnv = Readonly<{
30
31
  }>;
31
32
  export declare function previewOrigins(env: StandalonePreviewEnv): Promise<PreviewOrigins | null>;
32
33
  export declare class PreviewRefused extends Error {
34
+ readonly reason: PortPreviewIssueRefusal;
35
+ constructor(reason: PortPreviewIssueRefusal);
33
36
  }
34
37
  export type PreviewNative = Readonly<{
35
38
  accept: (ownerId: string) => void;
@@ -45,10 +48,12 @@ export declare function createStandalonePreview(storage: ConstructorParameters<t
45
48
  fetch(port: number, request: Request): Promise<Response>;
46
49
  };
47
50
  export declare function standalonePreviewRequest(request: Request, env: StandalonePreviewEnv, ownsComputer: (computerId: string) => Promise<boolean>, forward: (computerId: string, port: number, request: Request) => Promise<Response>): Promise<Response | null>;
48
- /** Establish a top-level same-site document before the owner's Strict-cookie POST. */
51
+ /**
52
+ * Issue a private port preview from the owner's own click on the host's
53
+ * confirm page (`OysterHost.portPreviewEntry`), never from a submit no person
54
+ * made.
55
+ */
49
56
  export declare function standalonePortEntryRoutes(ports: Readonly<{
50
57
  ownsComputer: (computerId: string) => Promise<boolean>;
51
- issue: (computerId: string, ownerId: string, port: number) => Promise<{
52
- previewUrl: string;
53
- } | null>;
58
+ issue: (computerId: string, ownerId: string, port: number) => Promise<PortPreviewIssue>;
54
59
  }>): import("../authorization.js").Routes<OysterEnv>;
@@ -1,11 +1,12 @@
1
1
  import * as Schema from "effect/Schema";
2
2
  import * as z from "zod";
3
- import { ComputerPortAccess, PortAccessError, } from "@fungi.computer/computer/port-access";
3
+ import { ComputerPortAccess } from "@fungi.computer/computer/port-access";
4
4
  import { selectionSchema } from "../index.js";
5
5
  import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
6
6
  import { computerPortInputSchema } from "@fungi.computer/computer-contract";
7
- import { owner, publicRoute, routes } from "../authorization.js";
8
- import { html } from "hono/html";
7
+ import { owner, routes } from "../authorization.js";
8
+ import { sameOriginRequest } from "../request-origin.js";
9
+ import { parsePortPreviewPort, portPreviewIssueSchema, portPreviewRefusalMessage, portPreviewRefusalStatus, } from "../port-preview-entry.js";
9
10
  export const previewSelectorSchema = Schema.Struct({
10
11
  ownerId: Schema.NonEmptyString,
11
12
  installationId: Schema.NonEmptyString,
@@ -60,16 +61,21 @@ export async function previewOrigins(env) {
60
61
  };
61
62
  }
62
63
  export class PreviewRefused extends Error {
64
+ reason;
65
+ constructor(reason) {
66
+ super(`Port preview ${reason}`);
67
+ this.reason = reason;
68
+ }
63
69
  }
64
70
  // The retained flat hostname uses the Computer's non-secret identity. Fleet
65
71
  // IDs have a computer_ prefix; configured standalone IDs can be simple labels.
66
72
  const hostnameComputer = z.string().regex(/^(?:computer_)?[a-z0-9]+$/u);
67
73
  function previewUrl(origins, computerId, port) {
68
74
  if (!hostnameComputer.safeParse(computerId).success)
69
- throw new PreviewRefused();
75
+ throw new PreviewRefused("invalid_computer_address");
70
76
  const label = `${computerId.replace("computer_", "computer-")}-${String(port)}`;
71
77
  if (label.length > 63)
72
- throw new PreviewRefused();
78
+ throw new PreviewRefused("invalid_computer_address");
73
79
  const result = new URL(origins.preview);
74
80
  result.hostname = `${label}.${result.hostname}`;
75
81
  return result;
@@ -160,49 +166,34 @@ export async function standalonePreviewRequest(request, env, ownsComputer, forwa
160
166
  return new Response(null, { status: 404 });
161
167
  return forward(computerId, port.data.port, request);
162
168
  }
163
- /** Establish a top-level same-site document before the owner's Strict-cookie POST. */
169
+ /**
170
+ * Issue a private port preview from the owner's own click on the host's
171
+ * confirm page (`OysterHost.portPreviewEntry`), never from a submit no person
172
+ * made.
173
+ */
164
174
  export function standalonePortEntryRoutes(ports) {
165
175
  const path = "/computers/:computerId/ports/:port";
166
- return routes()
167
- .get(path, publicRoute("a preview entry document; only the owner-admitted POST issues a token"), (context) => {
176
+ return routes().post(path, owner("direct"), async (context, { principal }) => {
168
177
  context.header("Cache-Control", "no-store");
169
- context.header("Referrer-Policy", "no-referrer");
170
- context.header("Cross-Origin-Opener-Policy", "same-origin");
171
- // Chromium applies form-action to the POST redirect as well. The fixed
172
- // same-origin form must be able to finish on the HTTPS preview site.
173
- context.header("Content-Security-Policy", "default-src 'none'; script-src 'unsafe-inline'; form-action https:; frame-ancestors 'none'; base-uri 'none'");
174
- return context.html(html `<!doctype html><title>Open preview</title>
175
- <main>
176
- <form method="post" action="${context.req.path}">
177
- <button>Open preview</button>
178
- </form>
179
- <script>
180
- document.forms[0].requestSubmit();
181
- </script>
182
- </main>`);
183
- })
184
- .post(path, owner("direct"), async (context, { principal }) => {
178
+ const refuse = (reason) => context.json({ error: reason, message: portPreviewRefusalMessage(reason) }, portPreviewRefusalStatus[reason]);
179
+ // Activation alone does not prove origin: a clicked sibling-site form
180
+ // can carry both user activation and the owner's Strict cookie.
181
+ if (!sameOriginRequest(context.req.raw))
182
+ return refuse("same_origin_required");
183
+ // Require a user-activated navigation, never an automatic entry submit.
184
+ if (context.req.header("Sec-Fetch-User") !== "?1")
185
+ return refuse("confirmation_required");
185
186
  const computerId = context.req.param("computerId");
186
187
  const portParam = context.req.param("port");
187
- const port = computerPortInputSchema.safeParse({
188
- port: Number(portParam),
189
- });
190
- if (!/^[1-9][0-9]{0,4}$/u.test(portParam) ||
191
- !port.success ||
192
- !(await ports.ownsComputer(computerId)))
193
- return context.body(null, 404);
194
- try {
195
- const issued = await ports.issue(computerId, principal.actor.memberId, port.data.port);
196
- if (issued === null)
197
- return context.body(null, 404);
198
- context.header("Cache-Control", "no-store");
199
- context.header("Referrer-Policy", "no-referrer");
200
- return context.redirect(issued.previewUrl, 302);
201
- }
202
- catch (cause) {
203
- if (cause instanceof PreviewRefused || cause instanceof PortAccessError)
204
- return context.body(null, 404);
205
- throw cause;
206
- }
188
+ const port = parsePortPreviewPort(portParam);
189
+ if (port === undefined)
190
+ return refuse("invalid_port");
191
+ if (!(await ports.ownsComputer(computerId)))
192
+ return refuse("computer_not_found");
193
+ const issued = portPreviewIssueSchema.parse(await ports.issue(computerId, principal.actor.memberId, port));
194
+ if (issued.kind === "refused")
195
+ return refuse(issued.reason);
196
+ context.header("Referrer-Policy", "no-referrer");
197
+ return context.redirect(issued.previewUrl, 302);
207
198
  });
208
199
  }
@@ -121,6 +121,9 @@ const standaloneRoot = (selectComputer) => {
121
121
  role: "owner",
122
122
  };
123
123
  },
124
+ // The owner confirms a port preview on the host's own page before the
125
+ // owner route below issues it.
126
+ portPreviewEntry: true,
124
127
  // Operator source seeding and owner builds share the one owner guard.
125
128
  ownerRoutes: (env, scope) => standaloneOwnerRoutes(env, scope, () => root.hostFor(env, scope))
126
129
  .include(standaloneCandidatePreview({
@@ -21,7 +21,7 @@ export declare const storageFrameMethods: {
21
21
  };
22
22
  } | {
23
23
  readonly kind: "rejected";
24
- readonly code: "invalid" | "unavailable" | "conflict" | "undeclared_key" | "scope_not_declared" | "owner_required" | "too_large" | "quota_exceeded";
24
+ readonly code: "invalid" | "unavailable" | "conflict" | "owner_required" | "undeclared_key" | "scope_not_declared" | "too_large" | "quota_exceeded";
25
25
  };
26
26
  requiredOperations: () => string[];
27
27
  };
@@ -39,7 +39,7 @@ export declare const storageFrameMethods: {
39
39
  };
40
40
  } | {
41
41
  readonly kind: "rejected";
42
- readonly code: "invalid" | "unavailable" | "conflict" | "undeclared_key" | "scope_not_declared" | "owner_required" | "too_large" | "quota_exceeded";
42
+ readonly code: "invalid" | "unavailable" | "conflict" | "owner_required" | "undeclared_key" | "scope_not_declared" | "too_large" | "quota_exceeded";
43
43
  };
44
44
  requiredOperations: () => string[];
45
45
  };
@@ -56,7 +56,7 @@ export declare const storageFrameMethods: {
56
56
  };
57
57
  } | {
58
58
  readonly kind: "rejected";
59
- readonly code: "invalid" | "unavailable" | "conflict" | "undeclared_key" | "scope_not_declared" | "owner_required" | "too_large" | "quota_exceeded";
59
+ readonly code: "invalid" | "unavailable" | "conflict" | "owner_required" | "undeclared_key" | "scope_not_declared" | "too_large" | "quota_exceeded";
60
60
  };
61
61
  requiredOperations: () => string[];
62
62
  };
@@ -2,6 +2,7 @@
2
2
  export declare function attemptWebhook(target: Readonly<{
3
3
  url: string;
4
4
  secret: string;
5
+ previousSecret?: string;
5
6
  }>, delivery: Readonly<{
6
7
  id: string;
7
8
  type: string;
@@ -4,7 +4,7 @@ export async function attemptWebhook(target, delivery) {
4
4
  try {
5
5
  const response = await fetch(target.url, {
6
6
  method: "POST",
7
- headers: await webhookHeaders(target.secret, delivery.id, delivery.type, Math.floor(Date.now() / 1000), delivery.body),
7
+ headers: await webhookHeaders(target.secret, delivery.id, delivery.type, Math.floor(Date.now() / 1000), delivery.body, target.previousSecret),
8
8
  body: delivery.body,
9
9
  signal: AbortSignal.timeout(10_000),
10
10
  });