@tomismeta/paperclip-aperture 0.1.2 → 0.2.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.
Files changed (5) hide show
  1. package/README.md +61 -24
  2. package/dist/manifest.js +5 -2
  3. package/dist/ui/index.js +1104 -463
  4. package/dist/worker.js +1702 -231
  5. package/package.json +3 -3
package/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  # Paperclip Aperture
4
4
 
5
- **A Focus view for Paperclip powered by Aperture's deterministic attention engine.**
5
+ **The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.**
6
6
 
7
- [![npm](https://img.shields.io/npm/v/%40tomismeta%2Fpaperclip-aperture?label=npm&color=2563eb)](https://www.npmjs.com/package/@tomismeta/paperclip-aperture)
7
+ [![paperclip-aperture npm](https://img.shields.io/npm/v/%40tomismeta%2Fpaperclip-aperture?label=paperclip-aperture&color=2563eb)](https://www.npmjs.com/package/@tomismeta/paperclip-aperture)
8
8
  [![aperture github](https://img.shields.io/badge/aperture-tomismeta%2Faperture-18181b)](https://github.com/tomismeta/aperture)
9
9
  [![npm aperture core](https://img.shields.io/npm/v/%40tomismeta%2Faperture-core?label=aperture%20core&color=0f766e)](https://www.npmjs.com/package/@tomismeta/aperture-core)
10
10
  [![paperclip](https://img.shields.io/badge/host-paperclip-2563eb)](https://github.com/paperclipai/paperclip)
@@ -15,6 +15,19 @@
15
15
 
16
16
  Paperclip Aperture adds a Focus surface to Paperclip that deterministically ranks approvals, issue activity, and other human-facing events into `now`, `next`, and `ambient`.
17
17
 
18
+ It is designed as a live attention layer, not an inbox clone:
19
+
20
+ - `now` shows the single most interrupting item
21
+ - `next` stages the queue behind it
22
+ - `ambient` keeps low-pressure awareness visible without demanding action
23
+
24
+ Put differently:
25
+
26
+ - Inbox tells you what changed
27
+ - Focus tells you what deserves attention now
28
+ - Inbox mirrors source records
29
+ - Focus re-stacks them into an operator-facing queue with recommended moves
30
+
18
31
  ## Install
19
32
 
20
33
  ```bash
@@ -32,30 +45,19 @@ Then install the plugin with the command above.
32
45
 
33
46
  After install, open Paperclip and use the `Focus` entry in the sidebar.
34
47
 
35
- ## Flow
48
+ ## Napkin Diagram
36
49
 
37
50
  ```text
38
- Paperclip events
39
- approvals / issues / human-facing signals
40
- |
41
- v
42
- paperclip-aperture
43
- normalize host facts into Aperture inputs
44
- |
45
- v
46
- Aperture Core SDK
47
- deterministically judge now / next / ambient
48
- |
49
- v
50
- Focus in Paperclip
51
- sidebar / page / widget
52
- |
53
- v
54
- human response
55
- approve / reject / request revision / acknowledge
56
- |
57
- v
58
- Paperclip updates, Focus reshuffles
51
+ +--------------+ +--------------+ +--------------+ +--------------+ +--------------+
52
+ | Arrive | | Translate | | Judge | | Show | | Respond |
53
+ | events | | facts | | attention | | surface | | action |
54
+ +--------------+ +--------------+ +--------------+ +--------------+ +--------------+
55
+ | | | | |
56
+ +-----> +-----> +-----> +-----> |
57
+
58
+ tool hooks explicit facts does this what the operator decision
59
+ from Paperclip from raw payloads deserve operator carried back
60
+ and agents attention now? actually sees to the tool
59
61
  ```
60
62
 
61
63
  ## What You Get
@@ -63,6 +65,12 @@ Paperclip updates, Focus reshuffles
63
65
  - a Focus surface inside Paperclip
64
66
  - ranked `now`, `next`, and `ambient` attention lanes
65
67
  - approval handling, including budget-specific approval semantics
68
+ - issue-aware operator language such as `review required`, `blocked`, and targeted recommended moves
69
+ - agent-aware routing that distinguishes known company agents from human/operator roles when issue text references them
70
+ - a plugin-local deterministic semantic mapping layer that interprets Paperclip issue, approval, and agent signals before publishing them into Aperture Core
71
+ - dynamic re-stacking so items can move between `now`, `next`, and `ambient` as new evidence arrives
72
+ - inline issue commenting from the Focus surface when a Paperclip issue supports written response
73
+ - durable acknowledge/suppression behavior backed by plugin state and ledger replay
66
74
  - a sidebar entry, page, and dashboard widget
67
75
 
68
76
  ## Package Boundary
@@ -71,6 +79,16 @@ This plugin treats Paperclip as the host runtime and UI shell, while embedding [
71
79
 
72
80
  It is a pure SDK integration: Aperture Core is used as-is inside a self-contained Paperclip plugin, with no changes to Aperture Core or Paperclip core.
73
81
 
82
+ For `0.2.0`, the boundary works like this:
83
+
84
+ - the plugin worker owns Aperture ingestion, replay, review state, and display composition
85
+ - Paperclip remains the system of record for issue and approval writes
86
+ - approval transport still goes through same-origin Paperclip HTTP APIs from the plugin UI because the current plugin SDK does not expose approval read/write clients
87
+ - the plugin intentionally publishes `ApertureEvent`s today, using a Paperclip-specific semantic mapping layer and ontology, rather than switching fully to `SourceEvent`
88
+ - that semantic layer includes reusable intent detectors, actor resolution against real company agents, downstream blocker extraction, and shared operator-language generation inside the plugin
89
+
90
+ The plugin has been validated against [`@tomismeta/aperture-core@0.3.0`](https://www.npmjs.com/package/@tomismeta/aperture-core).
91
+
74
92
  ## Development
75
93
 
76
94
  ```bash
@@ -86,9 +104,28 @@ Before releasing, run:
86
104
  pnpm release:check
87
105
  ```
88
106
 
107
+ For a live local Paperclip smoke test:
108
+
109
+ ```bash
110
+ pnpm build
111
+ npx paperclipai context set --api-base http://localhost:3100
112
+ npx paperclipai plugin uninstall tomismeta.paperclip-aperture --force
113
+ npx paperclipai plugin install --local .
114
+ npx paperclipai run -i default
115
+ ```
116
+
117
+ Then open `http://127.0.0.1:3100/APE/aperture` and verify:
118
+
119
+ - `Acknowledge` hides the active card and survives refresh
120
+ - `Next` promotes into `Now`
121
+ - issue comments post successfully from Focus
122
+ - approval actions update Focus correctly
123
+ - resolved blocker comments downgrade stale `Now` items
124
+
89
125
  ## Links
90
126
 
91
127
  - Plugin on npm: [`@tomismeta/paperclip-aperture`](https://www.npmjs.com/package/@tomismeta/paperclip-aperture)
128
+ - Roadmap and releasing: [docs/ROADMAP.md](./docs/ROADMAP.md)
92
129
  - Aperture GitHub repo: [tomismeta/aperture](https://github.com/tomismeta/aperture)
93
130
  - Aperture Core on npm: [`@tomismeta/aperture-core`](https://www.npmjs.com/package/@tomismeta/aperture-core)
94
131
  - Paperclip GitHub repo: [paperclipai/paperclip](https://github.com/paperclipai/paperclip)
package/dist/manifest.js CHANGED
@@ -1,14 +1,17 @@
1
1
  const manifest = {
2
2
  id: "tomismeta.paperclip-aperture",
3
3
  apiVersion: 1,
4
- version: "0.1.2",
4
+ version: "0.2.0",
5
5
  displayName: "Paperclip Aperture",
6
- description: "A Paperclip plugin powered by Aperture's deterministic attention and judgment engine.",
6
+ description: "The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.",
7
7
  author: "@tomismeta",
8
8
  categories: ["automation", "ui"],
9
9
  capabilities: [
10
10
  "events.subscribe",
11
+ "agents.read",
11
12
  "issues.read",
13
+ "issue.comments.read",
14
+ "issue.comments.create",
12
15
  "plugin.state.read",
13
16
  "plugin.state.write",
14
17
  "ui.dashboardWidget.register",