emviz 0.3.1 → 0.4.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,97 @@
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
+ ## External-agent commands
19
+
20
+ 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.
21
+
22
+ ### open
23
+
24
+ ```sh
25
+ emviz open <project-dir>
26
+ ```
27
+
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.
29
+
30
+ Keep the token private. Each server has its own in-memory session and history.
31
+
32
+ ### poll
33
+
34
+ ```sh
35
+ emviz poll --url "$URL" --token "$TOKEN" --agent "$AGENT_ID"
36
+ ```
37
+
38
+ Waits for up to 25 seconds and exits with one JSON result.
39
+
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.
41
+ - `status: "timeout"` means no request arrived during this poll. The agent can poll again.
42
+ - `status: "stopped"` ends the agent's loop.
43
+
44
+ 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.
45
+
46
+ ### reply
47
+
48
+ ```sh
49
+ emviz reply "$REQUEST_ID" "$REPLY_TEXT" --url "$URL" --token "$TOKEN" --agent "$AGENT_ID"
50
+ ```
51
+
52
+ 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.
53
+
54
+ The agent must describe its actual edits and checks. A failed reply does not imply that file edits were rolled back.
55
+
56
+ ### stop
57
+
58
+ ```sh
59
+ emviz stop --url "$URL" --token "$TOKEN"
60
+ ```
61
+
62
+ 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.
63
+
64
+ ### close
65
+
66
+ ```sh
67
+ emviz close --url "$URL" --token "$TOKEN"
68
+ ```
69
+
70
+ 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`.
71
+
72
+ ## Feedback limits
73
+
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.
75
+
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.
77
+
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.
79
+
80
+ ## Review views
81
+
82
+ **Current** shows the current model on disk.
83
+
84
+ **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
+
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.
87
+
88
+ 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
+
90
+ ## Agent workflow
91
+
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.
93
+
94
+ 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
+
96
+ ## Verification
97
+
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.
@@ -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): 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":"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"}