@foldspace_npm/harness 0.1.33 → 0.1.34

package/templates/agent-starter/agent/constants.ts

@@ -2,9 +2,23 @@ export const AGENT_API_NAME = {{AGENT_API_NAME_JSON}};
 export const PRODUCT_ID = {{PRODUCT_ID_JSON}};
 export const APP_DOMAIN = {{APP_DOMAIN_JSON}};
 
+/**
+ * Whether each of the product's customers has their own subdomain
+ * (acme.example.com, globex.example.com). Left undecided until the human has
+ * answered: `true` or `false` is their answer, never a guess.
+ */
+export const PER_CUSTOMER_SUBDOMAIN: boolean | undefined = undefined;
+
 /**
  * Empty until you capture the app's own XHR. A guessed host looks like it
- * worked. Include an explicit port if the app uses one.
+ * worked. One of:
+ * - `"https://api.example.com"` - every customer calls the same backend.
+ *   Include an explicit port if the app uses one.
+ * - `"/api"` - the backend is on the page's own host.
+ * - `"https://{subdomain}.api.example.com"` - each customer's backend carries
+ *   their subdomain; the runtime puts each user's own in.
+ * With `PER_CUSTOMER_SUBDOMAIN = true`, never the address you observed as it
+ * is: that is one customer's backend, and every user's agent would call it.
  */
 export const API_BASE = "";
 

package/templates/agent-starter/agent/utils.ts

@@ -14,6 +14,9 @@
  * - `apiFetch` - JSON + `Authorization: Bearer`. For any other sign-in, see
  *   "Custom auth" below.
  * - `apiFetchBinary` — same auth, raw bytes (file download).
+ * - `apiBaseUrl` — `API_BASE` for this page: `"/api"` on the page's own host,
+ *   `{subdomain}` filled with this user's own. A custom `apiFetch` builds its
+ *   URLs from it, never from `API_BASE` directly.
  * - `publicFetch` — no token; marketing / public origin only.
  * - `getAuthToken` / `parseJwt` / `redact` — session read and safe logging.
  * - `mapWithConcurrency` — cap parallel fetches over a list.

package/templates/agent-starter/claude-settings.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Written by foldspace init: the commands a build runs, allowed up front so the coding agent is not stopped one denial at a time. init and upgrade are left out on purpose, so they ask, like anything not listed. foldspace deploy is Foldspace-internal and never runs in a build.",
+  "$comment": "Written by foldspace init: the commands a build runs, allowed up front so the coding agent is not stopped one denial at a time. init and upgrade are left out on purpose, so they ask, like anything not listed; so is share upload, which sends a video out. foldspace deploy is Foldspace-internal and never runs in a build.",
   "permissions": {
     "allow": [
       "Bash(npx foldspace help:*)",
@@ -12,6 +12,8 @@
       "Bash(npx foldspace badge:*)",
       "Bash(npx foldspace published:*)",
       "Bash(npx foldspace record:*)",
+      "Bash(npx foldspace share inspect:*)",
+      "Bash(npx foldspace sync:*)",
       "Bash(npm install:*)",
       "Bash(npm run build:*)",
       "Bash(npm run typecheck:*)",

package/templates/agent-starter/skills/review-experience/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: review-experience
+description: Check an experience's code before every save of the agent's code - it returns only the data the answer needs, every write waits for the user's yes, and it reaches nothing the user cannot reach in the product. A serious finding stops the save. Use before each repo_write of agent code, after `npx foldspace build` passed - not for a save that only brings agent/runtime/ up to date.
+---
+
+# Review an experience before it is saved
+
+Saving puts the code where it can be published for every user of the
+product - each with their own data, their own role and their own sign-in.
+What was right for the builder's account in the test window has to be
+right for all of them. This review is the last look before that.
+
+`npx foldspace build` already checked what can be read off the code: one
+customer's address written in, the user's token leaving the page,
+secrets, calls to hosts the project does not name. Those are not repeated
+here, and cards may draw any markup they need. This review is the three things only
+someone who knows what the experience is for can judge.
+
+## When
+
+Before **every** save of agent code with `repo_write` - the first one and
+each one after. Run it on the experiences the save changes; a save of only
+the files a build put in `agent/runtime/` needs no review.
+
+Build first: a save waits for `npx foldspace build` with no errors, then
+this review.
+
+## 1. Least data
+
+What `execute` returns reaches the agent and the model, and for a view card
+it is what the agent answers from (rule 2 of the manual). Return the facts
+the answer needs, picked one field at a time - nothing else.
+
+Read each `execute` and each card `callback` and check:
+
+- **Fields are picked by name.** Never `res.data`, a whole record, or
+  `...record` from the API.
+  *"Which invoices are due?"* needs invoice number, amount, due date and
+  status - not the customer record they came with (address, phone, tax id,
+  notes, the account manager).
+- **Only the ids the card or the next action uses.** An internal id nothing
+  reads is data for nothing.
+- **Other people's details only when the question is about them.** A list of
+  deals needs the deal owner's name, not their email and phone.
+- **Rows the card shows, not the whole table.** Cap the list at what the card
+  draws (and say how many there are in all, if the answer needs it).
+
+**Serious:** a whole record or the raw response returned; personal details
+(email, phone, address, date of birth, payment details, government ids) the
+answer does not need. **Fix now, not serious:** an extra harmless field.
+
+## 2. A yes before every write
+
+The agent acts with the user's own sign-in: a write is the user writing.
+It happens only after the user said yes to exactly that change.
+
+Find every write in the experience: an `apiFetch` (or `fetch`) with
+`method` `POST`, `PUT`, `PATCH` or `DELETE`, a form post (`submitForm`), and
+any helper in `agent/api/` that calls one. For each:
+
+Every write gets the user's yes in one of two ways:
+
+- **A card (visual widget), on the user's press.** The card shows what will
+  change before they press - `recipes/create-a-record` has the shape.
+  *Cancel the Pro plan* is a card that says *"Cancel your Pro plan on 1
+  November? You keep it until then."* with **Cancel plan** and **Keep it**;
+  nothing is sent until **Cancel plan** is pressed, and **Keep it** or closing
+  the card writes nothing.
+- **Text only (no card): the action is marked confirmation required.** Set
+  `confirmation_required: true` and a short `confirmation_message` on the
+  action (the Foldspace action tools take both; in Agent Studio it is the
+  action's *confirmation required* setting). Foldspace then asks the user
+  before `execute` runs.
+
+- **It writes what the user saw** - the same record, the same values - and
+  nothing besides: no "mark as read", no second record on the side.
+- **It is never repeated by itself.** A write that timed out may have landed:
+  say so, as `recipes/update-meeting-notes` does, rather than sending it again.
+
+⚠️ One case may need neither - this is a reading of
+`recipes/update-meeting-notes`, not yet a confirmed rule: **adding one new
+thing whose words the user gave in the same message** (*"add this to the
+meeting notes: ..."*). Their message is the yes, as long as `execute` writes
+exactly what they said and returns what was written. When in doubt, a card or confirmation required.
+
+**Serious:** a write with neither a card nor confirmation required that removes, cancels, replaces or
+overwrites something; sends something to someone (an email, an invite, a
+message); spends or refunds money or changes a plan; changes who can see or
+do what; or touches more than one record. A write the user did not ask for.
+
+## 3. Nothing the user cannot reach in the product
+
+The experience may reach only what this user could reach in the product
+itself. The builder is often signed in as an owner or an admin; most users
+are not.
+
+- **Every call is one the product's own screens make**, seen with
+  `npx foldspace observe screen` on a screen `observe menu` lists - not a path
+  found in the app's code, in its API docs, guessed, or reached by typing an
+  address. `docs/app-profile.md` says how each endpoint was established.
+- **A screen only an admin sees stays an admin's.** When the builder's
+  account can see admin screens (Users, Billing, Settings for the whole
+  account, anything under `/admin`), ask the human once, as a choice:
+  *"Do all your users see <the screen>, or only admins?"* Only admins: this
+  experience is not for everyone - say so, and do not save it as one.
+- **Nothing widens the reach.** No `all=true`, `scope=account`,
+  `includeDeleted`, export-everything or impersonation calls. A user's,
+  team's or account's id comes from the session (`/me`,
+  `recipes/who-is-the-user`) or from an earlier action's result - never from
+  the user's or the model's words.
+- **Do not rely on the screen being hidden.** Some products hide a screen and
+  still answer its call for anyone signed in. The test is what the product
+  shows this kind of user, not what its backend lets through.
+
+**Serious:** a call to an endpoint no screen for this kind of user makes; an
+admin-only screen in an experience for everyone; an id that widens the reach
+taken from words.
+
+## 4. What happens next
+
+- **Nothing serious:** save. In chat, one line at most - *"Checked it before
+  saving."* Fix the not-serious ones in the same pass, before the save.
+- **Something serious:** do not save. It is your code: fix it - pick the
+  fields, move the write behind a card, drop the call - build again, and run
+  this review again. Then save.
+- **A serious finding only the human can settle** (whether regular users see
+  a screen, whether a write needs a card): ask as a choice, with the safe
+  option first, and save only after the answer settles it. Their answer goes
+  in `docs/app-profile.md`, with the date.
+- **Never save around it** - not "for now", not to dev only: dev is where their
+  users can be sent next.
+
+Nothing here is said to the human in these words: in chat it is *"it only
+shows the invoice details, not the whole customer record"*, *"cancelling
+asks the user first"* - what their users will see.

package/templates/agent-starter/skills/share-a-video/SKILL.md

@@ -182,7 +182,9 @@ If `ok` is false, find its `code` in the table below. If true, read the poster
 ended: each answer complete, none an error or "that action isn't available",
 and each one shows what its capabilities and line say. A bad one: offer
 another question for that use case, prove it, record again. If there is a
-`note` that it ran long, offer to drop the last scene.
+`note` that it ran long, offer to drop the last scene. If there is a
+`wideWindow` note, tell the human in one line and offer a narrower test window
+and a new recording; they decide.
 
 ## 6. Hand it over
 
@@ -230,7 +232,12 @@ Only on a yes:
 5. Tell them in one line that they get an email at the first view and a daily
    summary on days it is watched, and that you can show the numbers
    (`get_video_share_stats`) or delete the link (`delete_video_share`) whenever
-   they ask.
+   they ask. `publish_video_share` says whether those emails are on for this
+   share.
+6. They want the emails off, or back on: the tool
+   `set_video_share_notifications` with the `share_id` and
+   `email_notifications` (`false` stops them, `true` turns them on). It covers
+   that one video only.
 
 The tools refuse with a reason you pass on as it is: an EU account (share
 links are not offered there yet - send the file instead), a cap (shares per