@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,424 @@
+# HTTP
+
+HTTP services: an outgoing client and an incoming server.
+
+---
+
+## Available in
+
+| Runtime | Service IDs |
+|---|---|
+| hkp-rt | `http-client`, `http-server`, `http-server-subservices` |
+| hkp-node | `http-client`, `http-server-subservices` |
+| hkp-python | `http-client`, `http-server-subservices` |
+| Browser | `http-client` |
+
+The browser also has [Fetcher](./fetcher.md), the older outgoing service with a
+contract of its own, and [Output](./output.md) for POST egress.
+
+---
+
+## http-client
+
+### What it does
+
+Makes outgoing HTTP requests and emits the response body downstream. The
+request fires on each pipeline trigger, making it the server-side
+equivalent of the browser's [Fetcher](./fetcher.md) service.
+
+### Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `url` | `string` | Request URL, written in full — authority and path together |
+| `method` | `string` | HTTP method (`GET`, `POST`, `PUT`, `DELETE`, …) |
+| `headers` | `object` | Request headers as key-value pairs |
+| `body` | `string \| object` | Request body (for POST/PUT) |
+
+### Input / Output
+
+- **Input**: any value; may be merged into the request body
+- **Output**: HTTP response body, parsed as JSON if the Content-Type is `application/json`, otherwise a string
+
+#### A request that says where it is going
+
+`path`, `method` and `url` are configuration, which is right for a service
+calling one endpoint over and over. Where a board calls a *different* address
+per item — an episode written to its own path, a record fetched by its own id,
+an article fetched by its own link — the input may say so, in the same envelope
+the response comes back in:
+
+```json
+{
+  "meta": { "method": "put", "path": "/episodes/one.mp3", "contentType": "audio/mpeg" },
+  "binary": "…the bytes…"
+}
+```
+
+```json
+{ "meta": { "method": "get", "url": "https://example.com/articles/one" } }
+```
+
+What the input leaves unsaid stays as configured, so a board that names none of
+them is unaffected. `path` is a sub-path of a mount, exactly as the configured
+field is: a typed URL carries its own path and is not rewritten from a distance.
+`url` stands in for the configured `url` and for nothing more — so a resolved
+mount still wins over it, as it wins over the field.
+
+A response says which address it came from in `meta.url` too. Handed unchanged
+to a second client, it calls that address again rather than the second client's
+own; map the request you mean in between.
+
+On hkp-node and in the browser.
+
+### On hkp-node, hkp-python and the browser
+
+These implementations share the configuration above (and therefore, on the
+remote runtimes, the same UI panel), with these differences:
+
+| Property | Type | Description |
+|---|---|---|
+| `__hkpMount` | `string` | The resolved address of a mount, written by the board's coordinator. Takes precedence over `url`; not a field to author |
+| `path` | `string` | The sub-path of a **mount**, and of nothing else. A `url` is a whole URL and carries its own path, so `path` is ignored when the target is one |
+| `query` | `object` | Request parameters as a map, encoded onto the target — every target, unlike `path`, because escaping is a service a map performs and a written URL cannot. Appended to any the target already carries, so a `url` or `path` written with parameters of its own keeps them. Numbers and flags are sent as the text they read as |
+| `timeoutMs` | `number` | Abort the request after this long (default `10000`) |
+
+- It takes its body from the pipeline rather than from a URL template; `body`
+  is used only when nothing came down the pipeline.
+- Its output is `{meta, body?, binary?}` — the same shape
+  `http-server-subservices` produces for an incoming request, so a request
+  received on one runtime can be forwarded from another unchanged. `meta`
+  carries `status`, `statusText`, `url`, `headers` and `contentType`; the payload
+  is decoded into `body` when the content type says what the bytes mean, and kept
+  in `binary` when it does not.
+- A failed request passes nothing down the pipeline, rather than a fabricated
+  result. A response with an error status *is* a result — the request completed,
+  and what the server said is the board's business.
+- How the response reaches the services after it differs by runtime:
+  - **hkp-node:** the response is the service's answer — the runtime awaits it
+    and goes on with it. That is what lets a [Join](./join.md) hold a request as
+    a detour and come back with the response beside what it had, and an
+    [Iterator](./iterator.md) count what each item brought back.
+  - **Browser:** the run is deferred while the request is in flight and resumes
+    after the service with the response, still as the same run.
+  - **hkp-python:** a pass runs on a worker thread and is not awaited, so the
+    service stops the push and calls the rest of the pipeline itself when the
+    response arrives. A Join holding it as a detour does not get the response
+    back as the detour's result: put the request outside the detour, or run the
+    detour on hkp-node.
+- While a request is in flight it says so (`requesting`), and every outcome names
+  the `method` and the `url` actually called, the `status` (`0` when there was no
+  response at all) and an `error` (empty when there was none) — so a panel shows
+  this request's outcome rather than the previous one's still standing.
+
+`http-client-demo-board.json` is that as an app: a facade that composes a
+request — URL, path, parameters, headers, a JSON body — and sends it with the
+verb you press, then reads the status, headers and body off what the Monitor
+behind it received. The requests leave from the runtime rather than the browser,
+which is the reason to call an API this way at all: no CORS policy has a say in
+who can be called, and a credential in a header never reaches the page.
+
+#### Calling an endpoint whose address is assigned at load time
+
+Supported by every runtime's client (`__hkpMount` plus `path`; hkp-rt keeps its
+URL templating for the `url` case).
+
+This is what `path` is for. A mount's address is assigned by a runtime and
+resolved by the coordinator, so it is not the board's to write — which leaves a
+sub-path of it nowhere else to go. A typed `url` has somewhere: itself.
+
+A service that hosts an endpoint does not bind a port — its runtime assigns it a
+path and publishes the address. That address is not knowable when a board is
+written, so a client names the *service* instead, in the field it already calls
+its target:
+
+```json
+{
+  "serviceId": "http-client",
+  "state": {
+    "url": "hkp-mount://endpoint-node/echo-server",
+    "path": "/hello"
+  }
+}
+```
+
+The coordinator resolves that and configures the client's `__hkpMount` with the
+address, which then takes precedence. `url` is what a person writes and
+`__hkpMount` is what the run produced, so neither overwrites the other and the
+board keeps its reference when it is saved. A reference in either field means
+the owner has not published yet, and the client waits rather than calling
+anything. (Boards written before the split put the reference in `__hkpMount`;
+they still work.)
+
+Resolving that reference belongs to whoever coordinates the board — a runtime
+sees only its own services, while the reference names one somewhere else. The
+coordinator hands over the address once the owner publishes it, and until then
+the client waits rather than calling anything. See the **Mounts** concept page
+(`docs/content/concepts/mounts.md`) for why endpoints are assigned rather than
+chosen, and who resolves a reference.
+
+### In the browser
+
+Same service id, same state, same response shape — so a board moves a request
+between the browser and a runtime by moving the service, and the facade over it
+does not change. `http-client-browser-demo-board.json` is exactly that: the demo
+board above with its one runtime taken away.
+
+What changes is not the contract but who makes the call. In the browser the page
+does, which is the whole reason to choose it — there is no runtime to install,
+start or reach — and the whole reason not to:
+
+- The call goes through only where the API allows this origin. A blocked one
+  fails as a bare network error, because the browser does not tell the page why.
+- A credential in a header is in the page, and travels from the user's machine
+  rather than from a server.
+- `meta.headers` carries what the response *exposes*: everything, same-origin;
+  cross-origin, the CORS-safelisted headers plus whatever the server named in
+  `Access-Control-Expose-Headers`.
+- `userAgent` is kept, so a board written on another runtime round-trips, but
+  not sent: the browser reserves that header for itself.
+
+---
+
+## http-server
+
+### What it does
+
+Hosts an HTTP server. Each incoming HTTP request triggers the downstream
+pipeline with the request data as its input. Useful for receiving
+webhooks, building internal APIs, or accepting data from external services.
+
+### Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `host` | `string` | Interface to bind (e.g. `"0.0.0.0"`) |
+| `port` | `string \| number` | Port to listen on |
+
+### Input / Output
+
+- **Input**: not used (server triggers itself on incoming requests)
+- **Output**: incoming HTTP request data (method, path, body, headers)
+
+### What answers the caller
+
+Who handles a request depends on whether a nested pipeline is configured:
+
+| Nested pipeline | Answer comes from |
+|---|---|
+| configured | the nested pipeline |
+| none | the services after the server, and the rest of the board |
+
+**With subservices**, the nested pipeline is the handler and what it returns is
+what the caller gets. The services after the server still run, and their result
+still drives the next runtime — but they run *after the answer is decided*.
+That is where the side effects of having served a request belong: logging it,
+forwarding it, notifying something.
+
+**Without subservices**, the rest of the board is the handler. The request flows
+into the services after the server and whatever they return is the answer. This
+is the inversion of control the service is built around, and it is what lets a
+board answer an endpoint at all.
+
+Keeping the two apart is what makes a nested pipeline worth configuring: having
+declared a handler, you can add services behind the server without silently
+rewriting an HTTP contract from a distance. It also means a runtime that serves
+an endpoint can be made terminal with a [Stopper](./stopper.md) — ending the
+chain so it does not drive the runtime that calls it — while still answering its
+callers normally.
+
+### What a handler may answer with
+
+An answer is JSON unless the handler says otherwise, which is what every board
+got before there was a way to say anything else. To say otherwise, return the
+request envelope read backwards — `meta` beside `body` or `binary`:
+
+```json
+{
+  "meta": { "status": 200, "contentType": "application/rss+xml" },
+  "body": "<?xml version=\"1.0\"?><rss version=\"2.0\">…</rss>"
+}
+```
+
+| Field | Means |
+|---|---|
+| `meta.status` | the response status, **and what marks this as an answer** |
+| `meta.contentType` | the `content-type` header |
+| `meta.headers` | any other headers, by name |
+| `binary` | the bytes to send |
+| `body` | a string, sent as text; anything else, sent as JSON |
+
+A `body` that is an asset reference — `"hkp-asset://player"` — is sent as that
+[asset](../concepts/assets.md)'s content, resolved from the runtime's asset store
+when the answer is written, and with the asset's media type unless `meta` names
+one. Editing the asset changes the next response without reconfiguring the
+endpoint. One that does not resolve is answered `500`, naming the asset and why.
+On hkp-node, hkp-python and hkp-rt.
+
+**The status is what distinguishes an answer from a request.** A request and a
+response are the same shape, so a pipeline that passes its input through returns
+a request — and reading any `meta` as an answer would silently reply with the
+caller's own content type. A request carries no status; a response always does.
+It is also what [http-client](#http-client) reports a response as, so a board
+that proxies one endpoint to another passes what it got straight back.
+
+Raw bytes on their own are sent as `application/octet-stream`, because there is
+no JSON encoding of them anybody wanted.
+
+**Byte answers are seekable.** A `Range` header is honoured against the bytes
+the handler produced, and answered `206` with a `content-range`. That is what a
+player dragging a scrubber sends, and a server that ignores it re-sends the whole
+file each time.
+
+Available on hkp-node, hkp-python and hkp-rt. hkp-rt does not honour `Range` on
+an answer. An hkp-rt pipeline sends a page by putting it in the envelope, e.g. a
+[Static](./static.md) whose `out` is
+`{ "meta": { "status": 200, "contentType": "text/html; charset=utf-8" }, "body": "<!doctype html>…" }`.
+
+### The two ways in
+
+An endpoint is entered from two sides, and they are different jobs: a **request**
+arriving from outside, and a **pass** of the board's own chain flowing through.
+A board names the pipelines it wants for them.
+
+```json
+{ "onRequest": [ … ] }                        // requests; a pass goes through
+{ "onProcess": [ … ] }                        // passes; the board answers
+{ "onProcess": [ … ], "onRequest": [ … ] }    // both, separately
+{ "pipeline":  [ … ] }                        // one pipeline, entered from both
+```
+
+**Declaring `onRequest` is what takes the answer away from the chain.** With
+one, that pipeline is the handler: what it returns is what the caller gets. The
+services after the endpoint still run — that is where a board reacts to having
+served a request — but after the answer is decided. Without one, the request
+flows into the services after the endpoint and whatever they return is the
+answer, which is the inversion of control this service is built around.
+
+So an endpoint can have something to run on a pass — counting it, logging it —
+without silently becoming an HTTP handler.
+
+`pipeline` is the way to say *one pipeline, both entries*, which is the only way
+the two sides can share a service's state: they are one running thing rather
+than two.
+
+### Publishing a document
+
+A pass ends where it ends, so a value it produced is gone by the time a request
+arrives. An endpoint that publishes what the board last handed it keeps that
+value in a **slot** — cells the endpoint owns and lends to both its pipelines:
+
+```json
+{
+  "onProcess": [ { "serviceId": "hold", "state": { "slot": "document", "op": "write" } } ],
+  "onRequest": [ { "serviceId": "hold", "state": { "slot": "document", "op": "read"  } } ]
+}
+```
+
+See [Hold](./hold.md). Nothing here inspects the value, so anything can be
+published this way — a feed, a playlist, an audio file — and the two Holds may
+sit in pipelines that never meet.
+
+Because the answer is decided at the endpoint, a runtime may publish **more than
+one document**: two endpoints in one chain, each answering what reached it. The
+services after an endpoint still run on every request, though, so a feed and a
+playlist are better off one runtime each: a request should not drag a tail of
+SQL behind it.
+
+### Streaming
+
+A document is answered and done. A **stream** is the one answer that keeps
+coming: a caller on its path stays connected, and what every pass produces is
+written to it as it happens.
+
+```json
+{
+  "stream": { "path": "/live.mp3", "contentType": "audio/mpeg" },
+  "onProcess": [ { "serviceId": "audio-encode", "state": { "stream": true } } ]
+}
+```
+
+A `GET` on `path` is not a request to answer but a **listener to keep**. What the
+pass produces — `onProcess`'s result, or the pass's own input where there is no
+`onProcess` — goes to every listener at once. There is one stream, not one per
+listener, and the endpoint owns it because the connections are its own.
+
+| Property | Default | Means |
+|---|---|---|
+| `path` | — | where a player connects; declaring it is what turns the stream on |
+| `contentType` | `application/octet-stream` | what the stream is |
+| `burstBytes` | `0` | how much of the most recent stream a newcomer gets at once, so a player has something to buffer; `0` starts it at the next chunk |
+| `maxQueueBytes` | `32768` | how far one listener may fall behind before the oldest of what it has not been sent is dropped |
+| `stallTimeoutMs` | `5000` | how long a write may wait on a caller that has stopped reading before it no longer counts as listening |
+
+**Nobody holds up the stream.** Every write is asynchronous and every listener
+has its own queue, so a slow connection falls behind on its own. Past
+`maxQueueBytes` it loses its oldest unsent chunks — a gap, then back near the
+live edge — instead of drifting further behind for as long as it stays.
+
+**A caller that stops reading stops counting.** A paused player, or a request a
+browser parked instead of closing, keeps its connection open without hearing
+anything. Once a write has waited `stallTimeoutMs` it is let go. The wait only
+starts once the caller's own network buffers are full, so on a fast link that
+can take tens of seconds.
+
+**Chunks are the unit.** They are kept, replayed and dropped whole, so a stream
+whose chunks each start where a decoder can start — whole MP3 frames, as
+[Audio Encode](./audio-encode.md) emits in `stream` mode — can be joined at any
+point.
+
+**A range probe is answered, not streamed.** Before it plays anything, Safari
+asks for `Range: bytes=0-1` to learn what the resource is. A bounded range is
+answered `206` with that many bytes from the start of the latest chunk and a
+length of `*`, and the connection closes. Served the stream instead, the probe
+would stay open alongside the real request and count as a second listener. An
+open-ended range (`bytes=0-`) is a player streaming, and gets the stream.
+
+The response has no length and closes with the connection (`Connection:
+close`), which every player understands. Bytes, strings and MixedData's `binary`
+are streamed; anything else a pass produces is not. The state reports the
+`streamUrl`, how many `listeners` there are and, in `listenerDetails`, who they
+are — address, user agent, time connected, bytes sent; setting `stream` to `null` ends
+it and lets them go. Declaring a different stream ends the old one the same way
+— its listeners were answered under the old path and content type — and nothing
+it kept for late joiners or probes carries over; declaring the same one again
+changes nothing.
+
+**Where the passes come from is the board's business.** Whatever reaches the
+endpoint is streamed: the output of the service before it, the result of the
+runtime before this one, or messages a [websocket-reader](./websocket.md#on-hkp-node)
+takes in from a runtime elsewhere — a home machine behind a NAT feeding a relay
+in the cloud, say. The endpoint itself only fans out.
+
+On hkp-node the stream answers through the reverse proxy in front of the server
+too. It sends `X-Accel-Buffering: no`, so nginx passes it on at once instead of
+collecting it first.
+
+Available on hkp-rt and hkp-node.
+
+### The older spelling
+
+Boards written before the entry points had names carry a `mode` beside a single
+`pipeline`, and still load:
+
+| `mode` | Means |
+|---|---|
+| `process_on_session` | `onRequest` ← the pipeline |
+| `process_on_both` | both entries ← the same pipeline |
+| `process_on_data` | the slot arrangement above, built in and unnamed |
+
+It is the same endpoint either way. What `mode` could not express is an
+endpoint with a pipeline for passes and no handler — under the older rule,
+having a pipeline at all decided who answered.
+
+---
+
+## Typical pattern: API bridge
+
+Expose a lightweight HTTP endpoint in hkp-rt that processes data and
+sends the result to a browser:
+
+```
+http-server (port 8080) → map → websocket-server (port 8081)
+Browser:  Input (ws://hkp-rt:8081) → Canvas
+```

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

@@ -0,0 +1,79 @@
+# If
+
+Evaluates a structural pattern against incoming data and conditionally routes it through a nested sub-pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| hkp-rt | `if` |
+
+---
+
+## What it does
+
+If checks whether the incoming data matches a configured `condition` (a JSON subset pattern). If the condition matches, the data is routed through a nested `pipeline` of services and the result is early-returned from the outer pipeline — downstream outer services are skipped. If the condition does not match, the data passes through to the next outer service unchanged.
+
+### Condition matching
+
+The condition is evaluated as a structural subset test with AND semantics: every key–value pair in `condition` must be present and equal in the incoming data. Nested objects are matched recursively. For `MixedData` the condition is checked against the meta field; for plain JSON it is checked against the JSON object directly.
+
+```json
+{ "method": "GET" }
+```
+
+Matches when the incoming data has `method == "GET"`.
+
+```json
+{ "method": "POST", "path": "/upload" }
+```
+
+Both `method` and `path` must match (AND).
+
+---
+
+## Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `condition` | `object` | JSON pattern; all key–value pairs must match for the branch to execute |
+| `pipeline` | `ServiceDescriptor[]` | Ordered list of services to run when the condition is true |
+
+### Dynamic pipeline management
+
+Pipelines can be modified at runtime without replacing the full config:
+
+| Property | Effect |
+|---|---|
+| `appendService: { serviceId, state? }` | Appends a service to the end of the pipeline |
+| `removeService: "<instanceId>"` | Removes the service with the given instance ID |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any — checked against `condition` |
+| **Output (match)** | Result of the nested `pipeline` (early return) |
+| **Output (no match)** | Original input, forwarded to the next outer service |
+
+---
+
+## Example: route POST requests to a handler
+
+```json
+{
+  "serviceId": "if",
+  "state": {
+    "condition": { "method": "POST" },
+    "pipeline": [
+      { "serviceId": "map", "instanceId": "extract-body", "state": { "template": { "body=": "params.body" } } }
+    ]
+  }
+}
+```
+
+POST requests are processed by the inner Map; GET and other requests skip the branch entirely.

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

@@ -0,0 +1,46 @@
+# IFFT
+
+Computes the Inverse Fast Fourier Transform (IFFT) to reconstruct a time-domain signal from frequency-domain data.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| hkp-rt | `ifft` |
+
+---
+
+## What it does
+
+IFFT is the inverse of the [FFT](./fft.md) service. It expects a JSON array of complex frequency-domain coefficients (the output of FFT) and reconstructs the corresponding time-domain signal by applying the Cooley–Tukey IFFT algorithm.
+
+The output is a JSON array of real-valued samples. The window length is determined by the size of the input array.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `windowLength` | `number` | `512` | Expected window length in samples (informational; actual length is taken from the input array size) |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | JSON array of complex numbers `[re, im, re, im, ...]` or `[{ re, im }, ...]` |
+| **Output** | JSON array of real-valued time-domain samples |
+
+---
+
+## Typical use
+
+```
+FFT → [frequency-domain processing] → IFFT → AudioOutput
+```
+
+Apply spectral processing (e.g. filtering, pitch shifting) between FFT and IFFT to modify an audio signal in the frequency domain.

package/bundle/docs/content/services/image-picker.md

@@ -0,0 +1,50 @@
+# Image Picker
+
+Presents a file picker for images and emits the selected image as a `Blob` into the pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/image-picker` |
+
+---
+
+## What it does
+
+Image Picker provides a UI panel with a **Choose Image** button and a **Send** button. When the user picks an image file (JPEG, PNG, or any browser-supported format), a preview is displayed. Clicking **Send** emits the raw image `Blob` downstream.
+
+On mobile devices, the `capture="environment"` attribute on the file input allows the camera to be used directly.
+
+---
+
+## Configuration
+
+None. All interaction is through the UI panel.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | None (triggered by the UI) |
+| **Output** | `Blob` — the raw image file |
+
+---
+
+## Typical pipelines
+
+```
+Image Picker → ASCII Art → Monitor
+```
+
+Pick an image; ASCII Art converts it to a character grid.
+
+```
+Image Picker → OpenAI Prompt → Monitor
+```
+
+Send an image to a vision model for analysis.