@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/communication-dispatcher.md

@@ -0,0 +1,190 @@
+# Communication Dispatcher
+
+The manager in the middle of the star. Decides what to do next about an ongoing
+exchange, does it, and takes the result back.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Node.js (hkp-node) | `communication-dispatcher` |
+
+---
+
+## The shape it makes
+
+Around it sit the **actions** — a nested pipeline each, doing one thing a
+business does: understand what was asked, ask for what is missing, quote, send.
+
+```
+                    ┌── extract     read the enquiry, record what it says
+                    │
+poll → iterator → dispatcher ── follow-up   ask for what is missing
+                    │
+                    └── send        send the approved reply
+                          │
+                    transition      write down where the exchange got to
+```
+
+A board grows by gaining an **action**, not by gaining a runtime. The
+alternative — one runtime per step, each polling the state its step handles — is
+one board per business rule, and the workflow becomes something you reconstruct
+by reading five runtimes and noticing which states they select on.
+
+---
+
+## Why a model decides
+
+What arrives is a person writing an email, and no expression over `state`
+anticipates what they will say. The model is given what a new colleague would be
+given — the goal, the states the work can be in, the actions available and what
+each is for, and the exchange so far — and answers with one action and the state
+that follows if it works.
+
+Two things keep that from being a licence to invent.
+
+**The answer is constrained by a schema this service writes.** `action` and
+`next` are enums of what this dispatcher actually has, generated from its own
+configuration and pushed into whichever nested service takes a `jsonSchema`. An
+action that does not exist cannot be named, never mind run — and because the
+schema is derived rather than written out by hand beside the actions, it cannot
+drift out of step with them.
+
+**An action can declare when it is possible at all.** `available` is an
+expression over the input; an action whose precondition fails is not on the menu
+this turn. Sending an approved draft is not a judgement call when there is no
+approved draft. Narrowing the menu to the legal moves is what makes the choice
+good, and it is a different question from which legal move to make.
+
+### Waiting is one of the answers
+
+`wait` is always offered and never configured. Without it, a model asked to
+choose an action must choose one, and a conversation waiting on a customer gets
+a second follow-up because "none of these" was not among the things it could say.
+
+Waiting still allows the state to change — a manager reading a complete enquiry
+decides there is nothing further to obtain and moves it on. When the state named
+is the one the exchange is already in, nothing is passed on, so nothing after
+this writes a transition for a pass in which nothing happened.
+
+---
+
+## One action per pass
+
+The loop is the poll that fed this service, not a loop in here.
+
+The position of the machine is then a row someone can read rather than a stack
+frame; a restart resumes rather than restarts; and a model that changes its mind
+costs one call per tick instead of spending a budget in a cycle nobody is
+watching. An exchange needing four steps takes four ticks, which for email is
+nothing.
+
+The cost guard belongs on the poll, not here: [Conversations](./conversations.md)'
+`actionable` takes `idleSeconds`, so an exchange nothing has happened to is not
+reconsidered every thirty seconds.
+
+---
+
+## What the model is shown
+
+All of the input. What is worth knowing about an exchange is whatever the board
+put in front of this service — the thread, what has already been extracted, what
+has already been drafted — and a service that named the parts it understood
+would stop being general the first time a board added one. Use
+[Join](./join.md) to gather those beside the record rather than replacing it:
+
+```
+join (as: thread)  ┐
+                   └─ conversations (thread)
+join (as: known)   ┐
+                   └─ conversations (list-artifacts)
+communication-dispatcher
+conversations (transition)
+```
+
+`maxContextChars` bounds it, so one long attachment cannot cost a context window.
+
+---
+
+## What it hands the action
+
+```json
+{ "…the input…", "action": "follow-up", "reason": "…", "params": { "missing": ["numberOfRooms"] } }
+```
+
+`params` is the model's, and it is what makes an action reusable: one drafting
+action, told what to ask about, rather than one action per question a business
+might need to ask. Say in the action's `describe` what parameters it takes —
+that description is the only thing the model has to go on.
+
+The prompt for an action belongs **in** the action, not here. A dispatcher that
+generated every prompt would be the same baking in a different file.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `goal` | `string` | `""` | What the exchange is for |
+| `instruction` | `string` | *(a general one)* | Sent as the opening of the question. Not a system message: the decide pipeline may hold something that already has one, or may not be a model at all |
+| `states` | `array` | `[]` | `"name"` or `{ name, describe }`. The enum `next` is drawn from |
+| `stateFrom` | `string` | `"state"` | Dotted path to the current state in the input |
+| `actions` | `array` | `[]` | `{ name, describe, available, pipeline }` |
+| `decide` | `array` | `[]` | The pipeline that asks the model |
+| `maxContextChars` | `number` | `20000` | Bound on the input shown to the model. `0` = no bound |
+| `lastAction` / `lastReason` / `lastNext` | — | — | Read-only: what it decided, and why |
+
+Edits from the UI arrive branch-scoped — `{ branch: "<action name>" \| "decide", … }` —
+so one action's pipeline can be changed without rebuilding another's and
+destroying what is running in it.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | the exchange so far, as JSON |
+| **Output** | `{ …input, action, params, reason, result, state }` |
+| **Nothing** | when there is nothing to do and nothing to change, when the action produced nothing, or when the decision could not be read |
+
+An action producing nothing does not advance the exchange: the state the model
+named is the state that follows the action *working*.
+
+---
+
+## Example
+
+```json
+{
+  "uuid": "manager",
+  "serviceId": "communication-dispatcher",
+  "state": {
+    "goal": "Book a hotel room for the guest who wrote in.",
+    "states": [
+      { "name": "init", "describe": "nothing has been read out of it yet" },
+      { "name": "needs-follow-up", "describe": "something required is missing" },
+      { "name": "ready", "describe": "everything required is known" }
+    ],
+    "decide": [{ "serviceId": "text-generation", "uuid": "decide-llm", "state": { "…": "…" } }],
+    "actions": [
+      {
+        "name": "extract",
+        "describe": "Read the thread and record what the guest asked for. Takes no parameters.",
+        "pipeline": ["…"]
+      },
+      {
+        "name": "follow-up",
+        "describe": "Draft an email asking for details we still need. params: { missing: string[] }",
+        "available": "params.known.count > 0",
+        "pipeline": ["…"]
+      }
+    ]
+  }
+}
+```
+
+See `syn-conversations-demo-board.json` for the whole thing running.

package/bundle/docs/content/services/configurator.md

@@ -0,0 +1,66 @@
+# Configurator
+
+Routes a pipeline value to another service's `configure()` call instead of continuing downstream.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/configurator` |
+
+---
+
+## What it does
+
+Configurator is the dedicated routing primitive for dynamic reconfiguration. When a value arrives, Configurator calls `configure()` on the target service with the incoming value as the configuration payload, then either stops the pipeline chain (`passThrough: false`, default) or passes the original value downstream (`passThrough: true`).
+
+This separates concerns cleanly: Map transforms data, Configurator routes configuration — without coupling the upstream producer or the downstream target.
+
+### Cross-runtime targeting
+
+Set `targetRuntime` to configure a service in a different runtime (e.g. a remote hkp-rt instance). When `targetRuntime` is omitted, the target is looked up in the same runtime via `app.getServiceById()`.
+
+### Optional inner pipeline
+
+A `pipeline` list can be set to transform the incoming params before they reach the target service's `configure()`. This lets you reshape the upstream value into whatever shape the target's configure protocol expects — without touching either end.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `targetServiceUuid` | `string` | `""` | UUID of the service to configure |
+| `targetRuntime` | `string` | `undefined` | Runtime ID for cross-runtime targeting; omit for same-runtime |
+| `passThrough` | `boolean` | `false` | When `true`, the original value continues downstream after configuring the target |
+| `pipeline` | `PipelineEntry[]` | `[]` | Optional transform pipeline applied to params before `configure()` is called |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — passed as-is (or through `pipeline`) to the target's `configure()` |
+| **Output** | `null` (chain stops) when `passThrough: false`; original input when `passThrough: true` |
+
+---
+
+## Example: update a Map template from a Timer
+
+```json
+[
+  { "serviceId": "hookup.to/service/timer", "config": { "periodic": true, "periodicValue": 5, "periodicUnit": "s" } },
+  {
+    "serviceId": "hookup.to/service/configurator",
+    "config": {
+      "targetServiceUuid": "<uuid-of-map-service>",
+      "passThrough": false
+    }
+  }
+]
+```
+
+Every 5 seconds the timer tick is sent directly to the Map service's `configure()`, allowing dynamic template updates.

package/bundle/docs/content/services/conversations.md

@@ -0,0 +1,244 @@
+# Conversations
+
+Mail arrives in threads, threads are in states, and work produced along the way
+has to be found again. This service owns all three.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Node.js (hkp-node) | `conversations` |
+
+---
+
+## What it does
+
+Conversations is the domain half of a pair. [SQL](./sql.md) knows SQL and nothing
+else; this knows what a conversation *is*, and owns three tables that say so:
+
+| Table | Holds |
+|---|---|
+| `conversation` | one per thread: its state, subject, participants, and when it last moved |
+| `email` | every message, inbound and outbound, filed under its conversation |
+| `artifact` | anything the workflow produced — a draft reply, an extraction, a booking |
+
+A board that wants exactly these tables uses this. A board that wants different
+ones uses [SQL](./sql.md) and writes them itself.
+
+Both share one database per board, so a `sql` service beside a `conversations`
+one can query these tables directly — for a report the modes below do not cover.
+
+---
+
+## Threading
+
+**A conversation's id is the message id that began it**, worked out from mail
+headers alone:
+
+1. the conversation of any message already known from this one's `In-Reply-To`
+   or `References` chain, most specific first; failing that
+2. the oldest entry in that chain — so two replies to a root nobody ever saw
+   still land together; failing that
+3. the message's own id, because it is the first of its thread.
+
+Deterministic, and no board configures it.
+
+The cost of choosing headers over a subject-and-sender heuristic is real: a
+correspondent whose client drops `References` starts a new conversation. That is
+wrong, but wrong in the direction that leaves two threads to merge rather than
+two customers' bookings in one thread.
+
+### A message seen twice is not an event
+
+A mailbox poll re-delivers. The second delivery **stops the pipeline** — the
+same signal a [Store](./store.md) `get` miss gives — so the mail loop is safe to
+run on a timer without the board having to remember what it has seen.
+
+---
+
+## States are the board's
+
+The service does not know what `waiting-approval` means, and does not ship a
+state machine. The board declares its states, and every transition is checked
+against that list:
+
+```json
+{ "mode": "transition", "states": ["init", "waiting-approval", "waiting-reply", "done"] }
+```
+
+A state that is not on the list is **refused, not written**. That guard exists
+because of what usually writes a transition: a model deciding the next step. A
+state nothing selects on is indistinguishable from a conversation nobody is
+working on any more — the failure would surface as silence, days later.
+
+Leaving `states` empty accepts anything.
+
+Artifact statuses are deliberately *not* checked the same way. A status is set
+by a person pressing a button whose payload the board fixed, so a wrong value is
+a board bug that shows up the first time anyone presses it.
+
+---
+
+
+### Which database it keeps conversations in
+
+The **tenant** comes from the runtime, never from configuration. **Which file**
+inside it is the board's to say, through `database` — the same field and the
+same rules as [SQL](./sql.md): 1–64 characters from `A–Z`, `a–z`, `0–9`, `-` and
+`_`, not `shared`, and refused rather than silently replaced when it is not one.
+
+Left empty, the file is derived from the board's title, which is what every
+board did before the field existed — and the reason two boards sharing a title
+also share their conversations, and a renamed board appears to have lost them.
+Name it, and neither happens.
+
+Set the same name on every `conversations` and `sql` service that should see the
+same tables; this service does not read a board-level setting, because there
+isn't one.
+
+## Modes
+
+| Mode | What it does | Emits |
+|---|---|---|
+| `ingest` (default) | Files an email under its thread | `{ conversationId, state, isNew, participants, email }`, or **nothing** if already known |
+| `thread` | The conversation's emails, oldest first | `{ conversationId, emails: [...], count, lastInbound }` |
+| `transition` | Moves a conversation to another state | `{ conversationId, state, previous, updatedAt }` |
+| `actionable` | Conversations a poll should act on | `{ conversations: [...], count }` |
+| `put-artifact` | Keeps something the workflow produced | the artifact |
+| `list-artifacts` | Artifacts, oldest first | `{ artifacts: [...], count }` |
+| `set-artifact-status` | Records what was decided about one | the artifact |
+
+### Acting on what `actionable` found
+
+Whatever acts on a conversation acts on a **single** one — it reads the thread,
+decides, and writes back. But `actionable` says only what it found; iterating
+over it is [Iterator](./iterator.md)'s job, so a board can see the loop rather
+than have it buried in this service.
+
+```
+timer → conversations (actionable, inState: ["init"]) → iterator ┐
+                                                                 ├─ conversations   (thread)
+                                                                 ├─ text-generation (decide)
+                                                                 └─ conversations   (transition)
+```
+
+Point the Iterator at the list with `itemsFrom: "conversations"`. Each
+conversation then runs the nested pipeline once, as a run of its own.
+
+`idleSeconds` is what stops a poll picking the same conversation up on every
+tick while the last decision is still being carried out.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `string` | `"ingest"` | One of the seven above |
+| `states` | `string[]` \| `string` | `[]` | The declared state machine. Empty accepts anything |
+| `initialState` | `string` | `"init"` | What a newly threaded conversation starts in |
+| `direction` | `string` | `"inbound"` | `ingest`: `inbound` or `outbound`, unless the input says |
+| `state` | `string` | `""` | `transition`: a fixed target, for a step that always moves the same way |
+| `stateFrom` | `string` | `"state"` | `transition`: dotted path to the target in the input |
+| `conversationFrom` | `string` | `""` | Dotted path to the conversation id, e.g. `meta.conversationId` |
+| `inState` | `string[]` \| `string` | `[]` | `actionable`: which states count as work. **Required** |
+| `idleSeconds` | `number` | `0` | `actionable`: only conversations untouched this long |
+| `limit` | `number` | `100` | How many rows to take |
+| `kind` | `string` | `""` | Artifacts: the board's word for what this is |
+| `status` | `string` | `"pending"` | Artifacts: the status to write, or to filter on |
+| `payloadFrom` | `string` | `""` | `put-artifact`: dotted path to the part worth keeping |
+| `idFrom` | `string` | `""` | `set-artifact-status`: dotted path to the artifact id |
+| `lastCount` | `number` | — | Read-only: what the last pass saw |
+| `error` | `string` | — | Read-only: why the last pass produced nothing |
+
+**`lastInbound`** is the last message someone sent *to us*, separately from the
+list. A reply goes to whoever wrote in, and taking the last email instead is
+right only until we have sent one ourselves — at which point a board would
+quietly address its reply to its own sending address. It is `null` on a thread
+with nothing inbound in it.
+
+**`idFrom`** is for marking an artifact after acting on it. A pass that has just
+sent a message carries what was sent, not the draft it was sent from, so the
+board says where to look — `approved.artifacts.0.id`. Without it, the id has to
+be the input's own `id`, which means a Map reshaping the record purely to
+satisfy the next service.
+
+**Where the conversation id comes from**, in order: `conversationFrom` if it
+leads anywhere, then a `conversationId` field on the input, then a bare string
+input. `transition` takes its target state from `state` if the board fixed one,
+otherwise from `stateFrom` on the input.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | an email envelope (`ingest`), otherwise a conversation or artifact id |
+| **Output** | see the mode table above |
+
+`ingest` accepts exactly what [IMAP Email](./imap-email.md) emits —
+`{ messageId, subject, from, to, date, references, inReplyTo, text }` — with no
+mapping in between. `from`/`to` are the envelope's names and stay the envelope's
+names on the way out.
+
+Anything that goes wrong — an unknown conversation, an undeclared state, an
+`actionable` with nothing to poll for — is reported as `{ error }` and **passes
+nothing on**.
+
+---
+
+## Where it lives
+
+The same file per board as [SQL](./sql.md):
+
+```
+~/.hkp/node-<instance>/db/<sha256(owner)>/<sha256(board)>.db
+```
+
+The tables are created on first use. Deleting the file starts the board over;
+copying it takes that board's correspondence and nothing else.
+
+---
+
+## Example
+
+Mail in, threaded and queued for a decision:
+
+```json
+{
+  "uuid": "file-mail",
+  "serviceId": "conversations",
+  "serviceName": "Conversations",
+  "state": { "mode": "ingest", "initialState": "init" }
+}
+```
+
+Keeping a drafted reply for a person to look at:
+
+```json
+{
+  "uuid": "keep-draft",
+  "serviceId": "conversations",
+  "serviceName": "Conversations",
+  "state": {
+    "mode": "put-artifact",
+    "kind": "follow-up",
+    "payloadFrom": "followUp",
+    "status": "pending"
+  }
+}
+```
+
+And what the facade's `data-table` reads:
+
+```json
+{
+  "uuid": "pending-drafts",
+  "serviceId": "conversations",
+  "serviceName": "Conversations",
+  "state": { "mode": "list-artifacts", "kind": "follow-up", "status": "pending" }
+}
+```

package/bundle/docs/content/services/debounce.md

@@ -0,0 +1,45 @@
+# Debounce
+
+Rate-limits a pipeline by suppressing values that arrive before a configurable cooldown has elapsed.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/debounce` |
+
+---
+
+## What it does
+
+Debounce tracks the timestamp of the last value it forwarded. When a new value arrives, it computes the elapsed time since the last forward. If the elapsed time is less than `cooldown` seconds, the value is dropped (returns `null`) and the remaining cooldown is reported to the UI. If the cooldown has elapsed, the value is forwarded and the timestamp is reset.
+
+This is useful for noisy event sources such as button presses, sensors, or user interactions where you want at most one trigger per `cooldown` window.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `cooldown` | `number` | `60` | Minimum time between forwarded values, in seconds |
+| `reset` | `boolean` | — | When `true`, clears the last-fired timestamp so the next value is forwarded immediately |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value |
+| **Output** | The input value if the cooldown has elapsed; `null` otherwise |
+
+---
+
+## UI feedback
+
+The UI panel shows:
+- `lastFired` — timestamp (ms) of the last forwarded value
+- `remaining` — integer seconds until the cooldown expires; `null` when idle

package/bundle/docs/content/services/decrypt.md

@@ -0,0 +1,53 @@
+# Decrypt
+
+Decrypts a base64-encoded AES-256-GCM ciphertext produced by the Encrypt service.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/decrypt` |
+
+---
+
+## What it does
+
+Decrypt reverses the transformation applied by [Encrypt](./encrypt.md). It expects a base64 string whose raw bytes are `[12-byte IV][AES-256-GCM ciphertext]`, decrypts the ciphertext using the shared secret, and deserialises the plaintext back to the original JavaScript value.
+
+If the original value was a `Blob` or `File`, the encrypted form contained a base64-encoded wrapper; Decrypt reconstructs the `Blob` from it.
+
+### Key derivation
+
+The secret string is hashed with SHA-256 to produce a 256-bit AES-GCM key. The same secret must be set in both Encrypt and Decrypt.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `secret` | `string` | `""` | Shared secret used to derive the decryption key |
+| `method` | `"aes"` | `"aes"` | Encryption method (only AES-GCM is currently supported) |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Base64 string — `[12-byte IV][AES-256-GCM ciphertext]` |
+| **Output** | Original value (object, string, number, or `Blob`) |
+
+Returns `null` and emits an error notification if `secret` is not set or if the input is not a base64 string.
+
+---
+
+## Pairing with Encrypt
+
+```
+... → Encrypt → [transport / storage] → Decrypt → ...
+```
+
+Both services must be configured with the same `secret`. The encrypted payload is self-contained — the IV is embedded in the ciphertext string and a fresh IV is generated per encryption call.

package/bundle/docs/content/services/delay.md

@@ -0,0 +1,55 @@
+# Delay
+
+Applies a digital delay effect to an audio pipeline, adding an echo to the signal.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/delay` |
+
+---
+
+## What it does
+
+Delay is an audio effect service. It receives `FloatRingBuffer` frames from an upstream audio service, applies a delay-line algorithm (with feedback and wet/dry mix), and emits the processed audio downstream. Non-audio values are passed through unchanged.
+
+The delay algorithm uses a fixed circular buffer of up to 2000 ms. Each sample is read from a position offset by the delay time, blended with a configurable feedback level, and mixed with the dry signal.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `time` | `number` | `0.5` | Delay time in seconds |
+
+Additional internal parameters (not yet exposed via configure):
+
+| Parameter | Default | Description |
+|---|---|---|
+| `feedback` | `0.5` | How much of the delayed signal is fed back into the delay line (0–0.999) |
+| `mix` | `0.5` | Wet/dry blend (0 = dry only, 1 = wet only) |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `FloatRingBuffer` — audio sample frames |
+| **Output** | `FloatRingBuffer` — delay-processed audio |
+
+Non-`FloatRingBuffer` inputs are returned unchanged.
+
+---
+
+## Typical use
+
+```
+AudioInput → Delay → AudioOutput
+```
+
+Place Delay between an audio source and the audio output to add a reverb-like echo effect. Adjust `time` to control the echo offset.