@agentshouse/skills 0.1.0-c39c512127db6 → 0.1.0-c4bdfee08dfc8

package/guide/apps/example-function.md

@@ -43,7 +43,7 @@ export default async (event, house) => {
   const answer = await house.callExternal({
     url: `https://crm.example/cards/${card}`,
     method: 'PUT',
-    headers: { 'content-type': 'application/json', 'idempotency-key': event.occurrence },
+    headers: { 'content-type': 'application/json', 'idempotency-key': event.id },
     body: JSON.stringify({ status: 'assigned', manager: manager.fields.manager_id }),
     room_ref: event.room,
   });

package/guide/apps/functions.md

@@ -3,11 +3,11 @@
 How an App declares a function that House runs on its servers when a Trigger fires, with no page open and no model.
 
 - **Declare.** `app.json` lists `functions`, each `{"name": "assign lead", "entry": "functions/assign.js"}` ([App manifest](reference/app-manifest)). The entry is one ES module whose default export is the function and which imports nothing, so your build bundles each function, with all it imports, into `dist/`, such as `esbuild src/assign.ts --bundle --format=esm --outfile=dist/functions/assign.js`. A publish is refused whole for an entry that is missing, imports, has no default export or is over <function-size>, for a name used twice, and for more than <release-functions> functions.
-- **Run.** A Trigger's `function` action names the App and one of its functions ([Triggers](reference/triggers)). House runs the App's latest release when the occurrence's turn comes, one occurrence of a Trigger after another, so a run reads what the run before it wrote.
-- **The event.** `export default async (event, house) => {}` receives `kind`, the condition's `on`, with `room`, `trigger`, `occurrence`, `moment` and what matched: `path` and `reference`, a document change's `transition`, an arriving item's `item` with its `headers` and raw `body` text, or a dated document's `document`. `Date` reads `moment`. The return value is ignored, so write what you keep into the Room.
+- **Run.** A Trigger's `function` action names the App and one of its functions ([Triggers](reference/triggers)). House runs the App's latest release when the Event's turn comes, one Event of a Trigger after another, so a run reads what the run before it wrote.
+- **The event.** `export default async (event, house) => {}` receives `kind`, the condition's `on`, with `room`, `trigger`, `id`, `moment` and what matched: `path` and `reference`, a document change's `transition`, an arriving item's `item` with its `headers` and raw `body` text, or a dated document's `document`. `Date` reads `moment`. The return value is ignored, so write what you keep into the Room.
 - **The App API.** `house` is the page's App API over the Trigger's Room alone: `query(q)` ([Local Query](apps/local-query)), `saveParts(room, parts)`, `call(name, input)` for the Room acts such as `record.list` and `member.list`, and `callExternal(request)`. `query` and `callExternal` reject a refusal with its `code` for the function to catch, while `call` answers it as a result whose `kind` is `rejected` and `saveParts` as `outcome: 'refused'`, as on the page, so check what they answer. Its writes are the App's, by `App <App> (function <function>)`, fire Triggers, its own included, and count against the Room owner's Write limit.
 - **Reach.** A run holds no `fetch`, timer, file, `console` or `Intl`: keep times as ISO instants, or convert a local time by its UTC offset yourself. `callExternal` takes the request `bridge.callExternal` takes and is the one way out, to an origin the release's `external_origins` lists; naming its Room, `room_ref: event.room`, carries that Room's Service key, which the function never sees, or is refused `service_key_not_found` naming the `origin`. Its calls count against the Room owner's `external_calls` limit.
-- **Never repeated.** A run that started is never run again, even when it failed after a call reached the service. Send `event.occurrence` as the service's idempotency key where it takes one, and name what you write by what the event carries, so a second delivery of the same thing finds it.
-- **Failure and limits.** A throw settles the run `failed` with `function_failed` and its text, which `list_trigger_occurrences` shows and House tells the Room's owner; the next occurrence still runs. A run ends `failed` at <function-time>, at <function-memory> or past <function-calls> external calls: `time_cap_reached`, `memory_cap_reached` or `external_call_cap_reached`.
+- **Never repeated.** A run that started is never run again, even when it failed after a call reached the service. Send `event.id` as the service's idempotency key where it takes one, and name what you write by what the event carries, so a second delivery of the same thing finds it.
+- **Failure and limits.** A throw settles the run `failed` with `function_failed` and its text, which `list_trigger_events` shows and House tells the Room's owner; the next Event still runs. A run ends `failed` at <function-time>, at <function-memory> or past <function-calls> external calls: `time_cap_reached`, `memory_cap_reached` or `external_call_cap_reached`.
 
 Next: [Example: assign a lead](apps/example-function)

package/guide/reference/triggers.md

@@ -6,4 +6,4 @@ A Room's Triggers are its read-only `house-trigger` documents, one at `house/tri
 
 `condition`: When it fires, e.g. `{on: "documents", scope: {type: "task"}, mode: "starts_matching", new_documents: false, match: {all: [{path: "/fields/status", eq: "review"}, {path: "/members/assignee", eq: "<User id>"}]}}`; for a new document in a folder, `{on: "documents", scope: {folder: "/answers"}, mode: "starts_matching", new_documents: true, match: {all: []}}`; for any edit of one document, typed or plain, `{on: "documents", scope: {document: "/notes/plan.md"}, mode: "field_changes", field: "/text"}`; on documents, `moved_between_rooms: true` fires only on a document moved in from or out to another Room, `false` only on any other change; for arriving items, `{on: "items", address: "<push address>", match: {path: "/json/ref", eq: "refs/heads/main"}}`. A clock is `{on: "clock", cron: "0 9 * * 1", time_zone: "Europe/Berlin"}`, or a day before each task is due: `{on: "clock", scope: {type: "task"}, date: "/fields/due", days: -1, at: "09:00", time_zone: "Europe/Berlin", match: <test>}`. A `/fields/…` or `/members/…` path reads only what the document's own type declares, so under a folder scope a test matches only documents of a type that declares that field, House's built-in types among them: a document with no `type` has no fields, whatever its front matter holds, so give it a `type` naming one in `settings/schema.yaml` that declares the field.
 
-`actions`: What it does; a `notify` action names whom it reaches, e.g. `{kind: "notify", title: "Ready to test", text: "A task waits.", to: {users: ["<User id>"], fields: ["/members/assignee"], roles: ["owner"]}}`, Users by id, the member a field of the matched document names, and every holder of a Schema Role; a `routine` action names a Routine Access; a `function` action names an App and one function its latest release declares, e.g. `{kind: "function", app: "a_…", function: "assign lead"}`, which you may add only for an App you hold that has this Room in a write slot of your bindings; [App functions](apps/functions) says how House runs it. `list_trigger_occurrences` shows each run `ran` with its `release`, or `failed` with `function_failed` and its `error`, never run again, or `function_not_started` while House tries to start it, `final` after its last try.
+`actions`: What it does; a `notify` action names whom it reaches, e.g. `{kind: "notify", title: "Ready to test", text: "A task waits.", to: {users: ["<User id>"], fields: ["/members/assignee"], roles: ["owner"]}}`, Users by id, the member a field of the matched document names, and every holder of a Schema Role; a `routine` action names a Routine Access; a `function` action names an App and one function its latest release declares, e.g. `{kind: "function", app: "a_…", function: "assign lead"}`, which you may add only for an App you hold that has this Room in a write slot of your bindings; [App functions](apps/functions) says how House runs it. `list_trigger_events` shows each run `ran` with its `release`, or `failed` with `function_failed` and its `error`, never run again, or `function_not_started` while House tries to start it, `final` after its last try.

package/guide/skills/wizard.md

@@ -11,6 +11,10 @@ Write one bash script for the steps only the User can do: it says what to open a
 
 Create it with `create_web_wizard`, for the Environment you work through or another of the User's that they name (`list_environments`). Give the User the link it answers: they read the whole script there, and nothing runs until they press Run. Its output and what they type never reach you. When they say they are done, read the document at the path it answered, which says how it ended, and go on only once its state is finished with exit code 0.
 
+## As a function
+
+For a script the User may want to keep, propose a `name` when you create the Web Wizard. Only the User keeps a script: they tick Keep as a function on its page, may change the name, and press Keep, which runs nothing and makes the script one of their Environment functions. The document then reads `kept` with the function's name; keeping under a name they already use replaces that function's script. `inspect` on the Environment lists its functions, and `delete_function` deletes one.
+
 ## As a script they run
 
 When House refuses the Web Wizard because the Environment's Kit is not connected, because you reach no Environment of the User, or because the Environment you act through does not reach the User's Private Room, write the script into the Room where the Owner rules, `/rooms/private/owner-rules.md`, keep wizards, and give the User its link and the command that runs it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/skills",
-  "version": "0.1.0-c39c512127db6",
+  "version": "0.1.0-c4bdfee08dfc8",
   "description": "The upstream Skills agents.house serves its agents, verbatim, and the texts it writes for them: the Guide, its own Skills among the pages, and the Agent instructions",
   "license": "MIT",
   "type": "module",