@frondruntime/devtools 0.3.0

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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,23 @@
1
+ # Changelog
2
+
3
+ ## [0.3.0](https://github.com/frondruntime/frond/compare/devtools-v0.2.0...devtools-v0.3.0) (2026-07-28)
4
+
5
+
6
+ ### ⚠ BREAKING CHANGES
7
+
8
+ * **devtools:** `EncodedNodeSnapshot` drops `label` and `key`, so `HUB_PROTOCOL_VERSION` moves to 3. `label` was a presentation formatting of `tag` and `key` is already embedded in `nodeId`; both were duplicated on every row of a graph read. `kind` stays — "node" versus "resource" is not recoverable from either and decides whether release semantics apply.
9
+
10
+ ### Features
11
+
12
+ * **devtools:** runtime devtools, the frond-hub daemon, and MCP state reads ([#16](https://github.com/frondruntime/frond/issues/16)) ([0f3947e](https://github.com/frondruntime/frond/commit/0f3947ef4d51effd43f158390c9105aef5aae4b4))
13
+
14
+
15
+ ### Dependencies
16
+
17
+ * The following workspace dependencies were updated
18
+ * devDependencies
19
+ * @frondruntime/core bumped to 0.3.0
20
+ * peerDependencies
21
+ * @frondruntime/core bumped from 0.2.0 to 0.3.0
22
+
23
+ ## Changelog
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roman Dubinin and Frond Runtime contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,123 @@
1
+ # @frondruntime/devtools
2
+
3
+ Client half of the Frond devtools hub. One call attaches a runtime to a local hub, which streams its events in and can ask it what the graph looks like right now — both readable by a coding agent over MCP.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ bun add -d @frondruntime/devtools
9
+ ```
10
+
11
+ A dev dependency, not a runtime one. The intended shape is a call that only exists in development builds — see [Guarding it](#guarding-it) below.
12
+
13
+ An ordinary dual-entry ESM library: `.` for the attach client and `./node` for filesystem discovery, both shipped built, installable with any package manager and runnable on Node, Bun, a browser bundle, or React Native. The Bun requirement belongs to the hub daemon, not to this half — see [The hub](#the-hub).
14
+
15
+ `@frondruntime/core` and `effect` are peers. There are no runtime dependencies.
16
+
17
+ ## Attach
18
+
19
+ ```ts
20
+ import { attachDevtools } from "@frondruntime/devtools";
21
+
22
+ const detach = attachDevtools({ runtime, name: "my-app" });
23
+ ```
24
+
25
+ That is the whole configuration surface for the common case. With no `url`, it dials the hub's default address; with no `platform`, it guesses one from the environment. The returned function detaches.
26
+
27
+ Attaching never throws and never rejects. If no hub is listening it retries quietly every two seconds, so the call is safe to make before the hub starts, after it stops, and across restarts of either side. Pass `onError` if you want to see why it is not connecting.
28
+
29
+ "Forever" has one exception. A hub that *refuses* the attachment — today, only a protocol version mismatch — is answering a question about this build, and every retry would ask it again and get the same answer. So a refusal stops the loop and says so out loud, once, on the console. Supplying `onError` takes ownership of reporting it and silences that fallback. The alternative is what this used to do: redial every two seconds, silently, for the whole life of a process that was never going to attach.
30
+
31
+ ## What gets sent
32
+
33
+ The event stream, and — when the hub asks — a snapshot of the graph as it stands, which is what backs the hub's `frond_read_state` tool. Both go through the same encoder, so a node that is failing in a snapshot and the event that failed it read identically.
34
+
35
+ Values in either are redacted by default. `attachDevtools` declares a **ceiling** and the hub asks for a policy; the lesser of the two wins, and the ceiling defaults to `"shape"`:
36
+
37
+ | Policy | What a value looks like on the wire |
38
+ | --------- | ------------------------------------------------------------------------------------------ |
39
+ | `"none"` | The literal `"withheld"`, in place of every value |
40
+ | `"shape"` | A one-line descriptor: `{id,name,total}`, `Wired{_tag,run}`, `string[42]`, `Map(3)` |
41
+ | `"full"` | The value itself, bounded by depth, string length, entry count, and per-record value count |
42
+
43
+ ```ts
44
+ attachDevtools({ runtime, name: "my-app", values: "full" });
45
+ ```
46
+
47
+ Opt into `"full"` per app, deliberately. The runtimes worth debugging are the ones holding tokens and account state, and a default that ships values is a default that ships them the first time someone forgets. The hub always asks for `"full"` — once for the event stream when the attachment is accepted, and again on every state read — so the ceiling is the only thing standing between a reader and the data. That is the intended arrangement rather than a gap in it: the decision to put real values on a socket belongs to the app that owns them, not to the tool reading them.
48
+
49
+ `"none"` is its own encoder rather than a stricter `"shape"`, because a key list is itself a description of app data — an app that said it would send none should not be sending the key names of every node in a graph snapshot.
50
+
51
+ At `"shape"` the descriptors are strings rather than JSON objects, because this feed is read by an agent through MCP and a node result rendered as forty lines of pretty-printed JSON that contain no data is worse than one rendered as `{id,name}`. Numbers, booleans, and strings up to 256 characters still cross verbatim: in a runtime event those are ids, tags, timestamps, and flags, which is the entire signal. Anything structured is a descriptor, because a node result or an action input is always an object or an array. A class instance gives up only its type — `AccountModel{?}` — and `_tag` is the one nested field that survives, since a failure feed that says `{_tag,nodeId}` instead of `GraphNodeAcquireFailed` is not worth reading.
52
+
53
+ Every bound at `"full"` announces itself in the output: `{"_": "elided", "by": "depth"}` — or `"budget"`, or `"entries"` — where the walk stopped, and a `{"_": "string"}` descriptor carrying `length` and `head` where a string was cut. A cap a reader cannot see is worse than a low one, because it turns "there was more" into "that was all". Markers stay objects under a `_` key at this policy, where the values around them are real data and a marker has to remain distinguishable from one.
54
+
55
+ ### Failures
56
+
57
+ Failures are not values, and the policy table above only half applies to them. A failure crosses as its **chain of causes**, outermost first, because the outermost link is rarely the one worth reading — Frond wraps failures as it unwinds, and a `RefreshFailed` around an `AcquireFailed` around the thing your driver actually threw has an empty message of its own.
58
+
59
+ ```json
60
+ {
61
+ "_": "error",
62
+ "message": "upstream orders unavailable in eu-west (503)",
63
+ "causes": [
64
+ { "index": 0, "tag": "AcquireFailed", "nodeId": "feed:v1:…", "nodeTag": "feed" },
65
+ { "index": 1, "tag": "DriverPromiseFailed", "operation": "acquire" },
66
+ { "index": 2, "name": "Error", "message": "upstream orders unavailable in eu-west (503)" }
67
+ ]
68
+ }
69
+ ```
70
+
71
+ `message` is the deepest one that says anything — a hoisted field, not a summary. Each frame carries what the failure named: `tag`, `nodeId`, `operation`, `dependency`, `path`.
72
+
73
+ Messages cross at every policy including `"none"`, on the grounds that an app that has turned values off still wants to know what is failing. Two things are `"full"`-only: each frame's `stack`, and `fields` — the error's own payload, the `status` and `endpoint` and request id that a chain cannot name in advance.
74
+
75
+ To drop records entirely rather than redact them, filter:
76
+
77
+ ```ts
78
+ attachDevtools({
79
+ runtime,
80
+ name: "my-app",
81
+ include: (record) => !record.nodeIds.some((id) => id.startsWith("auth/")),
82
+ });
83
+ ```
84
+
85
+ ## Guarding it
86
+
87
+ ```ts
88
+ if (import.meta.env.DEV) {
89
+ attachDevtools({ runtime, name: "my-app" });
90
+ }
91
+ ```
92
+
93
+ The attach socket is unauthenticated by design — it only carries data *into* the hub, so an uninvited caller achieves nothing worse than junk in a dashboard. But the hub it dials is a plain loopback port with no notion of who is on the other end, so shipping a call to it in a production build points real user state at whatever answers. Guard it.
94
+
95
+ ## Platforms
96
+
97
+ The main entry imports nothing from `node:`. The transport is a global `WebSocket` carrying ndjson, so the same build attaches from a browser, from Bun, from Node, and from React Native.
98
+
99
+ Filesystem discovery lives behind its own export, so a browser bundler never has to resolve it:
100
+
101
+ ```ts
102
+ import { readHubLock } from "@frondruntime/devtools/node";
103
+
104
+ const lock = readHubLock(); // undefined when no hub is running
105
+ ```
106
+
107
+ `readHubLock` walks up from the working directory looking for `.frond/hub-<port>.json`, which a running hub writes and removes on exit. Useful for scripts that should do nothing when the hub is down.
108
+
109
+ ## The hub
110
+
111
+ The other half is `@frondruntime/hub`, a local daemon that holds the event history, asks attached apps for graph snapshots, and serves both to a coding agent over MCP:
112
+
113
+ ```sh
114
+ bunx @frondruntime/hub
115
+ ```
116
+
117
+ That daemon ships as TypeScript source and renders with Ink, so it needs Bun — `npx` cannot run it. Nothing about that reaches this package: the attach client is built ESM and runs wherever the app does. See its [README](../../apps/hub/README.md).
118
+
119
+ The two halves must agree on `HUB_PROTOCOL_VERSION` exactly, with no capability negotiation, because a partial mismatch presents as "the runtime stopped emitting" rather than as an error. A hub that sees a version it does not recognize refuses the attachment in one line naming both numbers and which side is behind, and this side stops retrying and prints it.
120
+
121
+ ## AI use
122
+
123
+ Frond is AI-assisted (mainly Claude and Codex), iterated over months rather than one-shot generated. Full note: https://frondruntime.dev/ai-use
@@ -0,0 +1,164 @@
1
+ // src/protocol.ts
2
+ import { Schema } from "effect";
3
+ import { Rpc, RpcGroup } from "effect/unstable/rpc";
4
+ var HUB_PROTOCOL_VERSION = 1;
5
+ var HUB_DEFAULT_PORT = 17391;
6
+ var HUB_DEFAULT_HOST = "127.0.0.1";
7
+ var HUB_ATTACH_PATH = "/attach";
8
+ var HUB_DEFAULT_ATTACH_URL = `ws://${HUB_DEFAULT_HOST}:${HUB_DEFAULT_PORT}${HUB_ATTACH_PATH}`;
9
+ var ValuePolicy = Schema.Literals(["none", "shape", "full"]);
10
+ var RuntimeEventCategory = Schema.Literals([
11
+ "command",
12
+ "diagnostic",
13
+ "input",
14
+ "lifecycle",
15
+ "operation",
16
+ "state"
17
+ ]);
18
+ var RuntimeEventSeverity = Schema.Literals(["debug", "error", "info", "warning"]);
19
+ var RuntimeEventTimeline = Schema.Literals(["live", "state", "system", "work"]);
20
+ var RuntimeWorkSource = Schema.Literals([
21
+ "react",
22
+ "mobx",
23
+ "node",
24
+ "manual",
25
+ "devtools",
26
+ "runtime",
27
+ "signal",
28
+ "test"
29
+ ]);
30
+ var RuntimeWorkReason = Schema.Literals([
31
+ "start",
32
+ "stop",
33
+ "readiness",
34
+ "retry",
35
+ "preload",
36
+ "refresh",
37
+ "action",
38
+ "args-update",
39
+ "live",
40
+ "release",
41
+ "eviction",
42
+ "unsafe-update",
43
+ "input",
44
+ "signal"
45
+ ]);
46
+ var RuntimeWorkPriority = Schema.Literals(["blocking", "visible", "background", "idle"]);
47
+ var AttachmentInfo = Schema.Struct({
48
+ protocolVersion: Schema.Number,
49
+ instanceId: Schema.String,
50
+ runtimeId: Schema.String,
51
+ generation: Schema.Number,
52
+ name: Schema.String,
53
+ platform: Schema.String,
54
+ startedAt: Schema.Number,
55
+ values: ValuePolicy
56
+ });
57
+ var EncodedEventRecord = Schema.Struct({
58
+ sequence: Schema.Number,
59
+ recordedAt: Schema.Number,
60
+ tag: Schema.String,
61
+ category: RuntimeEventCategory,
62
+ severity: RuntimeEventSeverity,
63
+ timeline: RuntimeEventTimeline,
64
+ reportable: Schema.Boolean,
65
+ workId: Schema.Number,
66
+ parentWorkId: Schema.optional(Schema.Number),
67
+ source: RuntimeWorkSource,
68
+ reason: RuntimeWorkReason,
69
+ priority: RuntimeWorkPriority,
70
+ nodeIds: Schema.Array(Schema.String),
71
+ fields: Schema.Record(Schema.String, Schema.Unknown),
72
+ failures: Schema.Array(Schema.Unknown)
73
+ });
74
+ var EncodedNodeSnapshot = Schema.Struct({
75
+ nodeId: Schema.String,
76
+ tag: Schema.String,
77
+ kind: Schema.String,
78
+ state: Schema.String,
79
+ revision: Schema.Number,
80
+ status: Schema.Unknown,
81
+ liveDemand: Schema.Unknown,
82
+ operation: Schema.Unknown,
83
+ resultValidity: Schema.optional(Schema.Unknown),
84
+ failure: Schema.optional(Schema.Unknown),
85
+ operationFailure: Schema.optional(Schema.Unknown),
86
+ liveFailure: Schema.optional(Schema.Unknown),
87
+ result: Schema.optional(Schema.Unknown)
88
+ });
89
+ var EncodedGraphEdge = Schema.Struct({
90
+ from: Schema.String,
91
+ to: Schema.String,
92
+ dependency: Schema.String
93
+ });
94
+ var GraphSnapshot = Schema.Struct({
95
+ capturedAt: Schema.Number,
96
+ sequence: Schema.optional(Schema.Number),
97
+ runtimeId: Schema.String,
98
+ runtimeStatus: Schema.String,
99
+ graphStatus: Schema.String,
100
+ observedInputs: Schema.Number,
101
+ values: ValuePolicy,
102
+ nodes: Schema.Array(EncodedNodeSnapshot),
103
+ edges: Schema.Array(EncodedGraphEdge)
104
+ });
105
+ var GraphQuery = Schema.Struct({ _tag: Schema.tag("Graph") });
106
+ var NodeQuery = Schema.Struct({
107
+ _tag: Schema.tag("Node"),
108
+ nodeId: Schema.String
109
+ });
110
+ var StateQuery = Schema.Union([GraphQuery, NodeQuery]);
111
+ var QueryOutcome = Schema.Union([
112
+ Schema.Struct({ _tag: Schema.tag("Snapshot"), snapshot: GraphSnapshot }),
113
+ Schema.Struct({ _tag: Schema.tag("Failed"), reason: Schema.String })
114
+ ]);
115
+ var HubAttached = Schema.Struct({
116
+ _tag: Schema.tag("Attached"),
117
+ attachmentId: Schema.String,
118
+ values: ValuePolicy
119
+ });
120
+ var HubPing = Schema.Struct({
121
+ _tag: Schema.tag("Ping"),
122
+ at: Schema.Number
123
+ });
124
+ var HubQuery = Schema.Struct({
125
+ _tag: Schema.tag("Query"),
126
+ requestId: Schema.String,
127
+ query: StateQuery,
128
+ values: ValuePolicy
129
+ });
130
+ var HubCommand = Schema.Union([HubAttached, HubPing, HubQuery]);
131
+
132
+ class HubRejection extends Schema.TaggedErrorClass("HubRejection")("HubRejection", { reason: Schema.String }) {
133
+ }
134
+
135
+ class Attach extends Rpc.make("Frond.Attach", {
136
+ payload: { info: AttachmentInfo },
137
+ success: HubCommand,
138
+ error: HubRejection,
139
+ stream: true
140
+ }) {
141
+ }
142
+
143
+ class Ingest extends Rpc.make("Frond.Ingest", {
144
+ payload: {
145
+ attachmentId: Schema.String,
146
+ records: Schema.Array(EncodedEventRecord),
147
+ droppedSince: Schema.Number
148
+ }
149
+ }) {
150
+ }
151
+
152
+ class Reply extends Rpc.make("Frond.Reply", {
153
+ payload: {
154
+ attachmentId: Schema.String,
155
+ requestId: Schema.String,
156
+ outcome: QueryOutcome
157
+ }
158
+ }) {
159
+ }
160
+ var FrondHubRpcs = RpcGroup.make(Attach, Ingest, Reply);
161
+
162
+ export { HUB_PROTOCOL_VERSION, HUB_DEFAULT_PORT, HUB_DEFAULT_HOST, HUB_ATTACH_PATH, HUB_DEFAULT_ATTACH_URL, ValuePolicy, RuntimeEventCategory, RuntimeEventSeverity, RuntimeEventTimeline, RuntimeWorkSource, RuntimeWorkReason, RuntimeWorkPriority, AttachmentInfo, EncodedEventRecord, EncodedNodeSnapshot, EncodedGraphEdge, GraphSnapshot, GraphQuery, NodeQuery, StateQuery, QueryOutcome, HubAttached, HubPing, HubQuery, HubCommand, HubRejection, Attach, Ingest, Reply, FrondHubRpcs };
163
+
164
+ //# debugId=007FD883D686F65364756E2164756E21
@@ -0,0 +1,10 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../src/protocol.ts"],
4
+ "sourcesContent": [
5
+ "import { Schema } from \"effect\";\nimport { Rpc, RpcGroup } from \"effect/unstable/rpc\";\n\n/**\n * Wire contract between an attached Frond runtime and the hub.\n *\n * Direction of the RPC roles is deliberate and inverted from who dials: the\n * hub listens and is the RPC *server*, the app dials out and is the RPC\n * *client*. That keeps the app free of any listening socket, and it is the only\n * arrangement both `RpcServer.layerHttp` and `RpcClient.layerProtocolSocket`\n * support without a hand-written socket adapter on either side.\n *\n * Hub-to-app work (state reads, and later refresh and action invocation)\n * therefore does not travel as a plain RPC call. It rides the `Attach` response\n * stream as a `Query` command, and the app answers with a separate unary\n * `Reply` correlated by `requestId`. `Attach` is the only long-lived call.\n *\n * Version equality is exact, on both sides, and there is no capability\n * negotiation. That is a deliberate choice rather than an omission: `HubCommand`\n * is a schema union, so an app one version behind would fail to decode a command\n * it has never heard of and drop its socket — presenting as \"the runtime stopped\n * emitting\", which is the most expensive way this can fail. Refusing the\n * attachment outright says the same thing immediately and in words.\n *\n * The number counts published generations of *this contract*, and moves on its\n * own schedule — it is not derived from, and does not track, the npm version of\n * any package. Tying the two was the earlier arrangement and it was wrong in\n * both directions: a release that touched nothing on the wire still moved the\n * number and refused every app that had not upgraded, while a genuine schema\n * change inside one release moved nothing and let two builds that disagreed\n * attach to each other. Starting at 1 with the first published hub, so what the\n * number counts is generations anyone could have installed.\n */\nexport const HUB_PROTOCOL_VERSION = 1;\n\n/**\n * Unregistered, and chosen for the band rather than the number.\n *\n * Above 9999 to clear the entire dev-server zone — Vite, Metro, Expo, CRA,\n * Django, Storybook, the node inspector — and below 32768 so it can never\n * collide with an ephemeral source port on Linux, whose range starts there.\n *\n * Stable on purpose. Apps hardcode it, so a hub that drifted to the next free\n * port on a collision would leave them dialing nothing, which presents as \"the\n * runtime is not emitting\" — the most expensive way to fail.\n */\nexport const HUB_DEFAULT_PORT = 17391;\n\nexport const HUB_DEFAULT_HOST = \"127.0.0.1\";\n\nexport const HUB_ATTACH_PATH = \"/attach\";\n\n/** Where an app dials when it was given no explicit URL. */\nexport const HUB_DEFAULT_ATTACH_URL = `ws://${HUB_DEFAULT_HOST}:${HUB_DEFAULT_PORT}${HUB_ATTACH_PATH}`;\n\n/**\n * How much of a value crosses the wire.\n *\n * Negotiated in one direction only: the hub asks, and the app answers with the\n * lesser of the request and its own ceiling. The ceiling defaults to `\"shape\"`,\n * so an app sends structure until someone deliberately decides otherwise — the\n * decision to put real values on a socket should be one somebody made, not one\n * that came with the default.\n */\nexport const ValuePolicy = Schema.Literals([\"none\", \"shape\", \"full\"]);\nexport type ValuePolicy = typeof ValuePolicy.Type;\n\nexport const RuntimeEventCategory = Schema.Literals([\n \"command\",\n \"diagnostic\",\n \"input\",\n \"lifecycle\",\n \"operation\",\n \"state\",\n]);\n\nexport const RuntimeEventSeverity = Schema.Literals([\"debug\", \"error\", \"info\", \"warning\"]);\n\nexport const RuntimeEventTimeline = Schema.Literals([\"live\", \"state\", \"system\", \"work\"]);\n\nexport const RuntimeWorkSource = Schema.Literals([\n \"react\",\n \"mobx\",\n \"node\",\n \"manual\",\n \"devtools\",\n \"runtime\",\n \"signal\",\n \"test\",\n]);\n\nexport const RuntimeWorkReason = Schema.Literals([\n \"start\",\n \"stop\",\n \"readiness\",\n \"retry\",\n \"preload\",\n \"refresh\",\n \"action\",\n \"args-update\",\n \"live\",\n \"release\",\n \"eviction\",\n \"unsafe-update\",\n \"input\",\n \"signal\",\n]);\n\nexport const RuntimeWorkPriority = Schema.Literals([\"blocking\", \"visible\", \"background\", \"idle\"]);\n\n/**\n * Who is attaching.\n *\n * `runtimeId` is the runtime's own `runtime-N` counter and collides freely\n * across tabs, reloads, and processes; `instanceId` is minted once per\n * `attachDevtools` call and is the only field safe to use as an identity key.\n */\nexport const AttachmentInfo = Schema.Struct({\n protocolVersion: Schema.Number,\n /** Stable for the life of the attaching runtime, including across reconnects. */\n instanceId: Schema.String,\n runtimeId: Schema.String,\n /**\n * How many times this runtime had already attached before this connection.\n *\n * Zero on a first attach; anything higher means the socket dropped and came\n * back, which is the same thing as saying the events in between are gone.\n * Devtools are not durable by design — nothing bridges that gap — so this\n * field exists to make the gap visible rather than to let anyone close it.\n */\n generation: Schema.Number,\n /** Human label for the CLI list, e.g. the host app's package name. */\n name: Schema.String,\n /** Free-form origin hint: \"bun\", \"browser\", \"expo-ios\", … */\n platform: Schema.String,\n startedAt: Schema.Number,\n /** The strongest value policy this app is willing to honor. */\n values: ValuePolicy,\n});\nexport type AttachmentInfo = typeof AttachmentInfo.Type;\n\n/**\n * A runtime event, flattened and already redacted by the sender.\n *\n * `fields` holds JSON-safe shape descriptors, not live values — encoding\n * happens at observe time, because a `RuntimeEventRecord` carries live\n * references that keep mutating after the record is handed out. The descriptor\n * vocabulary is written down once, in `descriptors.ts`, and what each policy\n * produces lives with the walk that produces it — `describeShape` in `shape.ts`,\n * `describeFull` in `full.ts`, `describeError` in `cause.ts`. Nothing on this\n * side should restate any of it and drift.\n */\nexport const EncodedEventRecord = Schema.Struct({\n sequence: Schema.Number,\n recordedAt: Schema.Number,\n /** The `RuntimeEvent` `_tag`, e.g. \"GraphNodeLiveDemandChanged\". */\n tag: Schema.String,\n category: RuntimeEventCategory,\n severity: RuntimeEventSeverity,\n timeline: RuntimeEventTimeline,\n reportable: Schema.Boolean,\n workId: Schema.Number,\n parentWorkId: Schema.optional(Schema.Number),\n source: RuntimeWorkSource,\n reason: RuntimeWorkReason,\n priority: RuntimeWorkPriority,\n nodeIds: Schema.Array(Schema.String),\n /**\n * Keyed by the event's own field names, minus `_tag`.\n *\n * A record rather than `Unknown`: every consumer — the UI, and shortly the\n * MCP reader — looks fields up by name, and typing the container as unknown\n * only moves that cast to each of them. The *values* stay unknown, which is\n * the honest part: what a field holds depends on the negotiated policy.\n */\n fields: Schema.Record(Schema.String, Schema.Unknown),\n /**\n * What went wrong, as chains of causes rather than as single errors.\n *\n * Each entry is `{_: \"error\", message, causes}`, outermost cause first. The\n * runtime lifts these off the event's own fields, so the same failure also\n * appears in `fields` — encoded identically, so one failure never reads as\n * two. Present at every policy: `\"none\"` is a statement about values, and a\n * feed that cannot say what is failing is not worth reading.\n */\n failures: Schema.Array(Schema.Unknown),\n});\nexport type EncodedEventRecord = typeof EncodedEventRecord.Type;\n\n/**\n * One node, as it is right now.\n *\n * Split the same way `EncodedEventRecord` is: the fields a reader filters and\n * branches on are typed, and anything that came out of the app's own data is\n * `Unknown`, because what it holds depends on the negotiated policy. Giving\n * `NodeStatus`, `NodeOperation` and the rest real schemas here would copy core's\n * type surface into the wire contract and guarantee the two drift apart.\n *\n * Every field here has to earn its place in *every row* of a graph read, which\n * is why core's `label` and `key` are not among them: `label` is a formatting of\n * `tag` and `key` is already inside `nodeId`, so both are the same fact charged\n * twice, a few hundred times per snapshot.\n */\nexport const EncodedNodeSnapshot = Schema.Struct({\n nodeId: Schema.String,\n /** The spec's tag, e.g. `\"orders\"`. Shared by every key; `nodeId` is the identity. */\n tag: Schema.String,\n /**\n * `\"node\"`, `\"service\"`, `\"resource\"` or `\"facade\"` — the one identity field\n * nothing else here implies.\n *\n * It says whether this row owns a release: a resource holds something the app\n * has to give back, and a reader deciding what a leak looks like cannot get\n * that from `tag` or `nodeId`.\n *\n * Carried as a string rather than a literal union so a hub can read an app\n * built against a core that has since grown a kind. Version equality already\n * gates the wire; making this field the second thing that can reject a\n * snapshot would buy nothing.\n */\n kind: Schema.String,\n /**\n * Which arm of core's `NodeSnapshot` this is: `Unwired`, `Idle`, `Pending`,\n * `Ready`, `ReadinessError`, `Releasing`, `Invalid`.\n *\n * Typed and hoisted because it is the one field every reader branches on.\n * Left inside the encoded `status` it would oblige an agent to understand this\n * encoder's descriptors before it could ask which nodes are broken.\n */\n state: Schema.String,\n /**\n * Core's per-node write counter, carried verbatim.\n *\n * The cheap way to tell \"still the value I saw last time\" from \"recomputed,\n * and happens to look the same\" — which no amount of comparing encoded\n * results can answer once a policy has redacted them.\n */\n revision: Schema.Number,\n status: Schema.Unknown,\n liveDemand: Schema.Unknown,\n operation: Schema.Unknown,\n resultValidity: Schema.optional(Schema.Unknown),\n /**\n * Why this node is not usable, as a chain of causes.\n *\n * Same encoding as `EncodedEventRecord.failures`, deliberately: a node failed\n * in the snapshot and the event that failed it should read identically.\n */\n failure: Schema.optional(Schema.Unknown),\n /**\n * The last operation that failed, as `{operationId, kind, at, error}`.\n *\n * Distinct from `failure`, and the difference is the whole point of keeping\n * it: a node can be `Ready` on a stale-but-valid result while its most recent\n * refresh failed. `failure` would be absent and everything would look fine.\n */\n operationFailure: Schema.optional(Schema.Unknown),\n /** Why live demand could not be served, as `{at, failures}`. */\n liveFailure: Schema.optional(Schema.Unknown),\n /**\n * The node's current value.\n *\n * Only ever present on a single-node query. A graph read of a few hundred\n * nodes is a topology question, and answering it with every result attached\n * would put the whole application state on the wire to draw a diagram.\n */\n result: Schema.optional(Schema.Unknown),\n});\nexport type EncodedNodeSnapshot = typeof EncodedNodeSnapshot.Type;\n\nexport const EncodedGraphEdge = Schema.Struct({\n from: Schema.String,\n to: Schema.String,\n /** The dependency name the dependent declared, not the target's tag. */\n dependency: Schema.String,\n});\nexport type EncodedGraphEdge = typeof EncodedGraphEdge.Type;\n\n/**\n * The graph at one instant.\n *\n * The counterpart to the event stream rather than a replacement for it: events\n * say what happened, this says what is true. `capturedAt` and `sequence` are\n * what let a reader hold both at once — a snapshot taken \"as of sequence 4412\"\n * can be lined up against the log the reader already has, instead of being a\n * second account of the same system with no way to relate them.\n */\nexport const GraphSnapshot = Schema.Struct({\n capturedAt: Schema.Number,\n /**\n * The last event sequence the runtime had recorded when this was taken.\n *\n * Absent on a runtime that has not emitted yet, which is the only honest\n * answer — zero would claim a position in a log that has none.\n */\n sequence: Schema.optional(Schema.Number),\n runtimeId: Schema.String,\n runtimeStatus: Schema.String,\n graphStatus: Schema.String,\n observedInputs: Schema.Number,\n /**\n * The policy the app actually applied, which may be less than was asked for.\n *\n * Stated per snapshot rather than inferred from the attachment: a reader that\n * finds no `result` on a node needs to tell \"redacted\" from \"not ready\", and\n * those are the same absence.\n */\n values: ValuePolicy,\n nodes: Schema.Array(EncodedNodeSnapshot),\n edges: Schema.Array(EncodedGraphEdge),\n});\nexport type GraphSnapshot = typeof GraphSnapshot.Type;\n\n/** Every node and edge, with statuses but without results. */\nexport const GraphQuery = Schema.Struct({ _tag: Schema.tag(\"Graph\") });\n\n/** One node, with its result and the edges incident on it. */\nexport const NodeQuery = Schema.Struct({\n _tag: Schema.tag(\"Node\"),\n nodeId: Schema.String,\n});\n\nexport const StateQuery = Schema.Union([GraphQuery, NodeQuery]);\nexport type StateQuery = typeof StateQuery.Type;\n\n/**\n * The app's answer to one query.\n *\n * `Failed` rather than an RPC error because the reply is a separate call from\n * the request: an error on this channel would fail the *reply*, which is not\n * the thing that went wrong, and would leave the hub waiting out its timeout\n * for an answer that already came back.\n */\nexport const QueryOutcome = Schema.Union([\n Schema.Struct({ _tag: Schema.tag(\"Snapshot\"), snapshot: GraphSnapshot }),\n Schema.Struct({ _tag: Schema.tag(\"Failed\"), reason: Schema.String }),\n]);\nexport type QueryOutcome = typeof QueryOutcome.Type;\n\n/** Hub accepted the attachment and assigned it an id. */\nexport const HubAttached = Schema.Struct({\n _tag: Schema.tag(\"Attached\"),\n attachmentId: Schema.String,\n /** What the hub is asking for. The app may downgrade, never upgrade. */\n values: ValuePolicy,\n});\n\n/** Liveness probe; the app answers by continuing to hold the stream open. */\nexport const HubPing = Schema.Struct({\n _tag: Schema.tag(\"Ping\"),\n at: Schema.Number,\n});\n\n/**\n * Asks the app what is true right now.\n *\n * Rides this stream because the hub has no way to call the app — it listens and\n * the app dials, so the only open channel in this direction is the `Attach`\n * response. The answer comes back as a separate `Reply` call rather than in\n * band, which is why `requestId` exists.\n *\n * `values` is requested per query, not per attachment. A stream of events and a\n * deliberate read of one node are different acts: the first is a firehose worth\n * keeping cheap, the second is someone asking a specific question. Both are\n * still clamped by the app's own ceiling, so this widens nothing the app has not\n * already agreed to.\n */\nexport const HubQuery = Schema.Struct({\n _tag: Schema.tag(\"Query\"),\n requestId: Schema.String,\n query: StateQuery,\n values: ValuePolicy,\n});\n\n/** Server-to-client commands. */\nexport const HubCommand = Schema.Union([HubAttached, HubPing, HubQuery]);\nexport type HubCommand = typeof HubCommand.Type;\n\n/**\n * The hub refused the attachment.\n *\n * `reason` is prose for a terminal, not a code to branch on. It is the last\n * thing said on a connection that is about to close, and the symptom on the\n * other end — devtools that quietly never appear — carries no information at\n * all, so the string has to carry the diagnosis and the next step instead. The\n * hub's version mismatch names both versions and which side to upgrade.\n *\n * Specific on purpose, where a rejection elsewhere would be deliberately vague:\n * there is no authentication on this call (see `Attach`), so an uninvited\n * caller learns nothing here it could not learn by dialing and observing, and\n * vagueness would cost only the developer who is actually trying to attach.\n */\nexport class HubRejection extends Schema.TaggedErrorClass<HubRejection>(\"HubRejection\")(\n \"HubRejection\",\n { reason: Schema.String }\n) {}\n\n/**\n * Opens the attachment and holds it open.\n *\n * The stream's lifetime *is* the attachment's lifetime: when the socket drops,\n * the handler is interrupted, which is how the hub learns about detachment.\n * There is no explicit detach call and there should not be one — a crashed app\n * cannot send it.\n *\n * Unauthenticated on purpose. Browsers do not apply CORS to WebSockets, so any\n * page a developer visits can dial a loopback port — but this direction only\n * carries data *into* the hub, so the worst an uninvited caller achieves is\n * putting junk in a dashboard. The direction where app data leaves is the MCP\n * endpoint, and a secret on this half while that one is open would buy nothing\n * and cost every host app a value to configure.\n *\n * The consequence, stated plainly because something downstream has to honour\n * it: records arriving here are not proof of their own origin, and a consumer\n * that feeds them to an agent is feeding it untrusted text.\n */\nexport class Attach extends Rpc.make(\"Frond.Attach\", {\n payload: { info: AttachmentInfo },\n success: HubCommand,\n error: HubRejection,\n stream: true,\n}) {}\n\n/**\n * Pushes a batch of events.\n *\n * `droppedSince` is the sender's count of records it could not buffer since the\n * previous batch. It is not optional and not a nicety: a devtools feed that\n * silently loses events is worse than one that admits to a gap, because an\n * agent reasoning over the stream cannot tell \"did not happen\" from \"was\n * dropped\".\n */\nexport class Ingest extends Rpc.make(\"Frond.Ingest\", {\n payload: {\n attachmentId: Schema.String,\n records: Schema.Array(EncodedEventRecord),\n droppedSince: Schema.Number,\n },\n}) {}\n\n/**\n * Answers one `Query`.\n *\n * A unary call in the app-to-hub direction, correlated by `requestId`, because\n * the RPC roles only run that way — see the note at the top of this file. The\n * consequence worth naming: a reply is not causally tied to the stream that\n * asked for it, so the hub has to time its requests out. An app that dies\n * mid-query simply never calls this.\n */\nexport class Reply extends Rpc.make(\"Frond.Reply\", {\n payload: {\n attachmentId: Schema.String,\n requestId: Schema.String,\n outcome: QueryOutcome,\n },\n}) {}\n\nexport const FrondHubRpcs = RpcGroup.make(Attach, Ingest, Reply);\n"
6
+ ],
7
+ "mappings": "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",
8
+ "debugId": "007FD883D686F65364756E2164756E21",
9
+ "names": []
10
+ }