emviz 0.3.2 → 0.5.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/README.md CHANGED
@@ -2,11 +2,158 @@
2
2
 
3
3
  Interactive visualizer for Event Modeling YAML projects.
4
4
 
5
+ ## Viewer commands
6
+
5
7
  ```sh
6
8
  npx emviz
7
9
  npx emviz .
8
10
  npx emviz sync .
11
+ npx emviz diff HEAD~1
12
+ npx emviz diff --from ../old-model --to .
9
13
  pnpm dlx emviz
10
14
  ```
11
15
 
12
- `emviz` starts a local Vite server for exploring an Event Modeling project. In project mode, it creates `.event-modeling/graph.json` automatically when missing. Run `emviz sync` to explicitly create or update `.event-modeling/graph.json`.
16
+ `emviz [project-dir]` starts the local viewer in the foreground. With no directory, the browser offers manual import. Project mode creates `.event-modeling/graph.json` when the sidecar is missing. `emviz sync` creates or updates the sidecar explicitly.
17
+
18
+ ## Host and security
19
+
20
+ `--host <IP>` and `--host=<IP>` select the listening address for foreground,
21
+ `serve`, `open`, and `diff` commands. The default is `127.0.0.1`.
22
+
23
+ ```sh
24
+ emviz . --host "$TAILSCALE_IP"
25
+ emviz open . --host "$TAILSCALE_IP"
26
+ emviz diff HEAD~1 --host "$TAILSCALE_IP"
27
+ emviz . --host ::1
28
+ ```
29
+
30
+ Use a specific IP assigned to the server machine. IPv4 and IPv6 literals are
31
+ supported. IPv6 viewer URLs use brackets. Wildcards such as `0.0.0.0` and `::`,
32
+ DNS names, URLs, and scoped IPv6 addresses are rejected. The server does not
33
+ discover an address, enable Tailscale, or change firewall rules.
34
+
35
+ For remote listeners, every API request requires the session capability,
36
+ including model reads and session snapshots. The server accepts only the
37
+ configured IP and actual listening port in the Host header. An Origin header
38
+ must match that exact HTTP origin. This does not authorize other hosts or CORS
39
+ origins.
40
+
41
+ For remote project sessions, the printed `viewerUrl` contains the capability in
42
+ a URL fragment. Remote manual-import and diff modes print the complete viewer
43
+ link without feedback connection JSON. The browser
44
+ removes the fragment and keeps the capability in tab-scoped session storage so
45
+ reloads work. Static app files do not contain the capability. Anyone with the
46
+ private viewer link can read the model and control its feedback session.
47
+ Never post the link or token in shared logs, tickets, screenshots, or public chat.
48
+
49
+ Use an encrypted private network such as Tailscale with appropriate access rules.
50
+ emviz uses plain HTTP. On an ordinary LAN or the public Internet, model data and
51
+ capabilities are visible in transit. Do not expose this server through a public
52
+ proxy. Close the owned server when finished to invalidate its capability.
53
+
54
+ Browsers can block clipboard APIs on non-loopback HTTP origins. If a copy button
55
+ does not work, select and copy the displayed text manually. Some existing copy
56
+ controls do not show a failure message.
57
+
58
+ CLI `poll`, `reply`, `stop`, and `close` accept a clean HTTP origin using a
59
+ concrete IP or the legacy `localhost` alias. They reject credentials, paths,
60
+ queries, fragments, DNS destinations, and redirects. Use exactly the returned
61
+ `url`; `viewerUrl` is for the browser.
62
+
63
+ `pnpm dev` starts Vite's manual-import development app. It is separate from the
64
+ project server and this CLI option.
65
+
66
+ ## External-agent commands
67
+
68
+ These commands connect an agent that the user starts separately. The server does not invoke an LLM, call a model provider, or edit canonical YAML on the agent's behalf.
69
+
70
+ ### open
71
+
72
+ ```sh
73
+ emviz open <project-dir>
74
+ ```
75
+
76
+ Starts a detached server and exits after startup. The default host is `127.0.0.1`.
77
+ Standard output contains a JSON object with `url`, `viewerUrl`, `token`, `pid`, and
78
+ `next_step`. Open `viewerUrl` in the browser. Use the clean `url` for CLI commands.
79
+ The token authorizes feedback operations. The PID identifies the server owned by
80
+ this open command.
81
+
82
+ Keep the token private. Each server has its own in-memory session and history.
83
+
84
+ ### poll
85
+
86
+ ```sh
87
+ emviz poll --url "$URL" --token "$TOKEN" --agent "$AGENT_ID"
88
+ ```
89
+
90
+ Waits for up to 25 seconds and exits with one JSON result.
91
+
92
+ - `status: "request"` includes `request` and `next_step`. The request includes its ID, feedback message, selected node reference, source path, source YAML, connected context, and project root. A batch adds `clientBatchId` and an ordered `items` array. Each item includes its captured ID, node ID, reference, revision, message, source path, YAML, and context. The top-level node identifies the first item. The top-level message and context include every item for older agents.
93
+ - `status: "timeout"` means no request arrived during this poll. The agent can poll again.
94
+ - `status: "stopped"` ends the agent's loop.
95
+
96
+ An agent uses a stable, unique ID and one foreground poll at a time. It processes each request serially and replies before polling again. A competing agent or a second in-flight poll receives an error.
97
+
98
+ ### reply
99
+
100
+ ```sh
101
+ emviz reply "$REQUEST_ID" "$REPLY_TEXT" --url "$URL" --token "$TOKEN" --agent "$AGENT_ID"
102
+ ```
103
+
104
+ Completes a claimed request with a reply from the same agent. The agent edits the project's canonical YAML directly before replying. A successful reply freezes the completed turn's after snapshot.
105
+
106
+ The agent must describe its actual edits and checks. A failed reply does not imply that file edits were rolled back.
107
+
108
+ ### stop
109
+
110
+ ```sh
111
+ emviz stop --url "$URL" --token "$TOKEN"
112
+ ```
113
+
114
+ Stops feedback and releases waiting polls. The viewer stays open, and files remain unchanged by the stop operation. **Resume session** in the browser reopens feedback. An agent whose poll loop exited must start polling again.
115
+
116
+ ### close
117
+
118
+ ```sh
119
+ emviz close --url "$URL" --token "$TOKEN"
120
+ ```
121
+
122
+ Closes the owned local server. Its in-memory request history ends with the process. This is the cleanup command for a server started by `open`.
123
+
124
+ ## Feedback limits
125
+
126
+ The browser's **Add to Queue** holds unsent items. **Send to Agent** submits the entire queue as one request. A session accepts one queued or working request at a time. Another request receives a busy error. A batch accepts 1 to 20 items, at most 4,000 characters per message, and at most 16,000 message characters in total. Replies accept at most 8,000 characters. The batch endpoint has a 128 KiB body limit. Other HTTP request bodies retain the 32 KiB limit. The session retains the latest 20 request records. Legacy single-node retries are recognized while their records remain in visible history. Batch receipts last for the server session, up to 1,000 distinct accepted batches. At capacity, new batches fail until the server restarts. An exact retry remains valid after its visible history row expires, but the old reply is no longer available.
127
+
128
+ Project feedback reads at most 512 model files and 8 MiB per snapshot. Discovery stops after 10,000 directory entries. Configured sources and symlink targets must stay inside the selected project root. A selected source is limited to 64,000 characters, and connected context to 128,000 characters. Captured context across a batch is limited to 1 MiB.
129
+
130
+ The additive `POST /api/feedback/batch` accepts `{ clientBatchId, items: [{ id, nodeId, reference, revision, message }] }`. All items must refer to the same current snapshot. Invalid or stale items reject the whole batch before any agent receives it. Reusing an ID with different ordered contents fails. Existing `POST /api/feedback/request` clients remain supported.
131
+
132
+ Feedback operations require the session token. Loopback viewers obtain the token
133
+ from their same-origin session snapshot. Remote viewers use the private
134
+ `viewerUrl` described below. The agent passes the token through `--token`.
135
+
136
+ ## Review views
137
+
138
+ **Current** shows the current model on disk.
139
+
140
+ **Session diff** compares the current model with a fixed Git baseline captured at startup. If Git cannot provide a usable baseline, the viewer labels the startup snapshot fallback. Later commits do not move the session baseline.
141
+
142
+ **Turn diff** compares the snapshot at request claim with the snapshot after a successful reply. A batch has one claim, one reply, and one turn diff for all of its items. It remains frozen after completion. Changes made manually during that interval also appear in the turn diff. The diff does not establish authorship.
143
+
144
+ Feedback is unavailable for removed, stale, or ambiguous selections, for disconnected sessions, and in **Turn diff**. Manual imports and standalone exports remain read-only.
145
+
146
+ ## Agent workflow
147
+
148
+ The [emviz skill](../../skills/emviz/SKILL.md) gives the full agent procedure.
149
+ The existing [em-feedback skill](../../skills/em-feedback/SKILL.md) delegates to it. The agent opens the project, gives the user the URL, polls, handles one request, replies, and polls again.
150
+
151
+ Idle poll timeouts continue the loop. The agent must stay active or use a supported
152
+ continuation mechanism. A detached server does not wake an idle LLM, and a skill
153
+ file alone cannot provide background execution.
154
+
155
+ The agent preserves unrelated file edits and does not commit, reset, or stash automatically. Restarting the server discards history, so an interrupted agent must re-read the project before continuing.
156
+
157
+ ## Verification
158
+
159
+ The [verify-emviz guide](../../.agents/skills/verify-emviz/SKILL.md) records the executed local real-server feedback journey and the 17 fixture browser cases. The real-server actor journey, two-machine remote-access journey, and the full startup-baseline fallback browser journey remain unexecuted. Those local checks do not start a real LLM. Its browser script starts an isolated project and real CLI processes. It records screenshots, video, a Playwright trace, CLI output, and canonical file contents outside the disposable project.
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=actors.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"actors.test.d.ts","sourceRoot":"","sources":["../src/actors.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,11 @@
1
+ type Connection = {
2
+ url: URL;
3
+ token: string;
4
+ agent?: string;
5
+ positional: string[];
6
+ };
7
+ export declare function parseConnection(values: string[]): Connection;
8
+ export declare function runAgentCommand(command: string, values: string[]): Promise<void>;
9
+ export declare function openProject(entry: string, target: string, host?: string): Promise<void>;
10
+ export {};
11
+ //# sourceMappingURL=agent-cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-cli.d.ts","sourceRoot":"","sources":["../src/agent-cli.ts"],"names":[],"mappings":"AAGA,KAAK,UAAU,GAAG;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAgB5D;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,SAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlG"}