emviz 0.4.0 → 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
@@ -15,6 +15,54 @@ pnpm dlx emviz
15
15
 
16
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
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
+
18
66
  ## External-agent commands
19
67
 
20
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.
@@ -25,7 +73,11 @@ These commands connect an agent that the user starts separately. The server does
25
73
  emviz open <project-dir>
26
74
  ```
27
75
 
28
- Starts a detached server on loopback and exits after startup. Standard output contains a JSON object with `url`, `token`, `pid`, and `next_step`. The URL opens the viewer. The token authorizes feedback operations. The PID identifies the server owned by this open command.
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.
29
81
 
30
82
  Keep the token private. Each server has its own in-memory session and history.
31
83
 
@@ -37,7 +89,7 @@ emviz poll --url "$URL" --token "$TOKEN" --agent "$AGENT_ID"
37
89
 
38
90
  Waits for up to 25 seconds and exits with one JSON result.
39
91
 
40
- - `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.
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.
41
93
  - `status: "timeout"` means no request arrived during this poll. The agent can poll again.
42
94
  - `status: "stopped"` ends the agent's loop.
43
95
 
@@ -71,11 +123,15 @@ Closes the owned local server. Its in-memory request history ends with the proce
71
123
 
72
124
  ## Feedback limits
73
125
 
74
- A session accepts one queued or working request at a time. Another request receives a busy error. Messages accept at most 4,000 characters. Replies accept at most 8,000 characters. HTTP request bodies have a separate 32 KiB limit. The session retains the latest 20 request records. Idempotent retries are recognized while their records remain in memory.
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.
75
127
 
76
- 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.
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.
77
129
 
78
- Feedback operations require the session token. The browser obtains its token from the same-origin session snapshot. The agent passes the token through `--token`. Do not expose the server through a network proxy or share its token.
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`.
79
135
 
80
136
  ## Review views
81
137
 
@@ -83,16 +139,21 @@ Feedback operations require the session token. The browser obtains its token fro
83
139
 
84
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.
85
141
 
86
- **Turn diff** compares the snapshot at request claim with the snapshot after a successful reply. It remains frozen after completion. Changes made manually during that interval also appear in the turn diff. The diff does not establish authorship.
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.
87
143
 
88
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.
89
145
 
90
146
  ## Agent workflow
91
147
 
92
- The [em-feedback skill](../../skills/em-feedback/SKILL.md) gives the full agent procedure. The agent opens the project, gives the user the URL, polls, handles one request, replies, and polls again.
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.
93
154
 
94
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.
95
156
 
96
157
  ## Verification
97
158
 
98
- The [verify-emviz guide](../../.agents/skills/verify-emviz/SKILL.md) is DRAFT and unexecuted for this change. 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.
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.
@@ -6,6 +6,6 @@ type Connection = {
6
6
  };
7
7
  export declare function parseConnection(values: string[]): Connection;
8
8
  export declare function runAgentCommand(command: string, values: string[]): Promise<void>;
9
- export declare function openProject(entry: string, target: string): Promise<void>;
9
+ export declare function openProject(entry: string, target: string, host?: string): Promise<void>;
10
10
  export {};
11
11
  //# sourceMappingURL=agent-cli.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"agent-cli.d.ts","sourceRoot":"","sources":["../src/agent-cli.ts"],"names":[],"mappings":"AAEA,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,CAe5D;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,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9E"}
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"}