pinglet-cli 0.1.4 → 0.1.6

package/README.md

@@ -64,10 +64,12 @@ install 시 `~/.claude/commands/pinglet.md` slash command가 함께 설치되며
   `node <cli> statusline`을 연결한다. statusline은 UI 영역이라 LLM context에
   전혀 들어가지 않으며(Zero Token), Thinking/Working 중에 메시지가 보인다.
   기존 statusLine 설정은 백업 후 uninstall 시 복원한다.
-  - **Spinner verbs** — `refresh` 배치가 feed를 받을 때 `spinnerVerbs`(mode:
-    "replace")에도 메시지를 등록해, "Befuddling…" 같은 기본 verb 자리에 Ping이
-    그대로 표시된다. Pinglet이 쓴 verb는 zero-width space 마커로 식별하므로
-    사용자가 직접 등록한 verb는 건드리지 않고, uninstall 시 원래대로 복원한다.
+  - **Spinner verbs (pool=1 회전)** — `spinnerVerbs`(mode: "replace")에 메시지를
+    **한 번에 하나만** 등록해 "Befuddling…" 자리에 Ping이 표시된다. statusline이
+    60초마다 다음 메시지로 교체하며, Claude Code가 설정을 핫리로드하므로 세션
+    중에도 즉시 반영된다. pool이 1개라 "spinner가 돌았다 = 이 메시지가 표시됐다"가
+    확정된다. Pinglet verb는 zero-width space 마커로 식별하므로 사용자가 직접
+    등록한 verb는 건드리지 않고, uninstall 시 원래대로 복원한다.
 - **Codex Adapter (experimental)** — `~/.codex/config.toml`의 `notify` hook에 연결.
   notify는 TUI 밖 프로세스라 터미널 안에 그릴 수 없어, MVP에서는 turn 완료 시
   macOS 알림으로 전달한다.
@@ -79,9 +81,11 @@ install 시 `~/.claude/commands/pinglet.md` slash command가 함께 설치되며
   네트워크가 절대 들어가지 않는다.
 - **오프라인 동작** — 서버 미연결 시 시드 메시지로 동작하고, 등록/feed 갱신은
   백그라운드 `refresh`가 온라인이 되면 자동 재시도한다.
-- **DELIVERED / QUALIFIED_IMPRESSION 분리** — 메시지 표시 시 DELIVERED를 기록하고,
-  30초 회전 주기에 3초 이상 유지된 메시지만 QUALIFIED_IMPRESSION(visibleMs 포함)으로
-  정산한다. 세션이 끊긴 구간은 마지막 tick까지만 노출로 계산한다.
+- **DELIVERED / QUALIFIED_IMPRESSION 분리** — 메시지가 spinner에 armed되면
+  DELIVERED(설치당 1회), armed된 동안 spinner가 3초 이상 실제로 돌았으면
+  QUALIFIED_IMPRESSION(visibleMs 포함)으로 정산한다. "실제로 돌았는지"는
+  statusline hook이 받는 `cost.total_api_duration_ms` 증가분으로 측정한다 —
+  pool이 1개이므로 API 활동 시간만큼 그 메시지가 표시된 것이 확정된다.
 - **Async Telemetry** — 이벤트는 `~/.pinglet/events.jsonl`(Local Event Queue)에
   append하고, 20개 이상 또는 60초 주기로 detached 프로세스가 batch 전송한다.
   전송 성공분만 큐에서 제거하므로 실패분은 자동 재시도되며, 재전송 중복은

package/dist/adapters/claude.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectClaude = detectClaude;
-exports.syncSpinnerVerbs = syncSpinnerVerbs;
+exports.armSpinnerMessage = armSpinnerMessage;
 exports.spinnerVerbsStatus = spinnerVerbsStatus;
 exports.isClaudeIntegrationInstalled = isClaudeIntegrationInstalled;
 exports.installClaudeIntegration = installClaudeIntegration;
@@ -184,11 +184,13 @@ function cleanupSpinnerTips(settings, config) {
     return true;
 }
 /**
- * Claude Code spinner verb("Befuddling…" 자리)를 feed 메시지로 교체한다.
- * mode: "replace"라 기본 verb 대신 Ping이 그대로 spinner 본문에 표시된다.
+ * Claude Code spinner verb("Befuddling…" 자리)에 메시지 **하나만** armed한다.
+ * pool을 1개로 유지해야 "spinner가 돌았다 = 이 메시지가 표시됐다"가 확정되고,
+ * cost 델타 기반 노출 측정(statusline)이 정확해진다. 설정은 핫리로드된다.
+ * message가 null이면 우리 verb를 걷어내고 기본 spinner로 되돌린다.
  * 마커가 붙은 항목만 Pinglet 소유로 보고 교체하며, 사용자 verb는 유지한다.
  */
-function syncSpinnerVerbs(config, messages) {
+function armSpinnerMessage(config, message) {
     const adapter = config.adapters.claude;
     if (!adapter)
         return false;
@@ -203,9 +205,8 @@ function syncSpinnerVerbs(config, messages) {
         (0, config_1.saveConfig)(config);
     }
     const userVerbs = existingVerbs.filter((verb) => !isPingletTip(verb));
-    const pingletVerbs = buildPingletVerbs(messages);
-    // 실제 feed 메시지가 없으면 spinner를 교체하지 않는다 —
-    // 우리가 넣어둔 verb가 있으면 걷어내고 Claude Code 기본 spinner로 되돌린다.
+    const pingletVerbs = message ? buildPingletVerbs([message]) : [];
+    // armed할 메시지가 없으면 spinner를 기본 상태로 되돌린다.
     if (pingletVerbs.length === 0) {
         if (!isOurs)
             return false;
@@ -224,10 +225,14 @@ function syncSpinnerVerbs(config, messages) {
         writeSettings(settings);
         return false;
     }
-    settings.spinnerVerbs = {
-        mode: "replace",
-        verbs: [...userVerbs, ...pingletVerbs],
-    };
+    const next = [...userVerbs, ...pingletVerbs];
+    // 같은 메시지를 다시 armed하는 경우 파일 쓰기를 생략한다 (300ms 렌더링 경로 보호).
+    if (existing?.mode === "replace" &&
+        existingVerbs.length === next.length &&
+        existingVerbs.every((v, i) => v === next[i])) {
+        return true;
+    }
+    settings.spinnerVerbs = { mode: "replace", verbs: next };
     writeSettings(settings);
     return true;
 }
@@ -265,7 +270,7 @@ function installClaudeIntegration(config, options = {}) {
     writeSettings(settings);
     installSlashCommand();
     // spinner verb는 로컬 캐시에 실제 feed가 있을 때만 채운다. 없으면 기본 spinner 유지.
-    syncSpinnerVerbs(config, (0, cache_1.loadFeedMessages)());
+    armSpinnerMessage(config, (0, cache_1.loadFeedMessages)()[0] ?? null);
     return { ok: true };
 }
 function uninstallClaudeIntegration(config) {

package/dist/commands/install.js

@@ -65,7 +65,7 @@ async function runInstall(args) {
             (0, cache_1.saveFeedMessages)(messages);
             if (messages.length > 0) {
                 console.log(`✓ Feed cached (${messages.length} messages)`);
-                if ((0, claude_1.syncSpinnerVerbs)(config, messages)) {
+                if ((0, claude_1.armSpinnerMessage)(config, messages[0] ?? null)) {
                     console.log("✓ Claude spinner synced");
                 }
             }

package/dist/commands/refresh.js

@@ -4,7 +4,6 @@ exports.runRefresh = runRefresh;
 const config_1 = require("../config");
 const api_1 = require("../api");
 const cache_1 = require("../cache");
-const queue_1 = require("../queue");
 const claude_1 = require("../adapters/claude");
 /**
  * 서버 feed를 미리 받아 Local Feed Cache를 갱신한다 (아키텍처 §6).
@@ -33,24 +32,14 @@ async function runRefresh() {
     const messages = await (0, api_1.fetchFeed)(config, records[0]);
     if (messages) {
         (0, cache_1.saveFeedMessages)(messages);
-        // 새 feed를 Claude Code spinner verb에도 반영한다 (설정 파일만 다시 쓰면 됨).
-        // feed가 비었으면 spinner를 기본 상태로 되돌린다.
-        (0, claude_1.syncSpinnerVerbs)(config, messages);
-        // spinner는 실제 노출 시점을 알 수 없으므로, spinner pool에 실린 시점을
-        // "전달(DELIVERED)"로 기록한다. 메시지당 설치 1회만.
-        if (config.adapters.claude && config.installations.CLAUDE) {
-            const state = (0, cache_1.loadState)();
-            state.delivered ??= {};
-            let changed = false;
-            for (const m of messages) {
-                if (state.delivered[m.id])
-                    continue;
-                (0, queue_1.appendEvent)({ agentType: "CLAUDE", type: "DELIVERED", messageId: m.id });
-                state.delivered[m.id] = 1;
-                changed = true;
-            }
-            if (changed)
-                (0, cache_1.saveState)(state);
+        // spinner 회전과 DELIVERED/QUALIFIED 기록은 statusline이 담당한다 (pool=1).
+        // 여기서는 armed된 메시지가 서버에서 사라진 경우만 즉시 정리한다.
+        const state = (0, cache_1.loadState)();
+        const current = state.current;
+        if (current && !messages.some((m) => m.id === current.messageId)) {
+            (0, claude_1.armSpinnerMessage)(config, messages[0] ?? null);
+            state.current = undefined; // 다음 statusline tick이 정식으로 다음 메시지를 armed한다
+            (0, cache_1.saveState)(state);
         }
     }
     // 이 기기에서 작성한 최근 메시지의 도달 통계를 갱신한다 (statusline 표시용).

package/dist/commands/statusline.js

@@ -1,20 +1,136 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runStatusline = runStatusline;
+const fs = __importStar(require("fs"));
+const config_1 = require("../config");
 const cache_1 = require("../cache");
 const render_1 = require("../render");
+const picker_1 = require("../picker");
+const queue_1 = require("../queue");
+const claude_1 = require("../adapters/claude");
 const runtime_1 = require("../runtime");
+function readPayload() {
+    try {
+        return JSON.parse(fs.readFileSync(0, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * cost.total_api_duration_ms 증가분 = 이 tick 사이에 spinner가 실제로 돈 시간.
+ * spinner pool이 1개이므로 그 시간만큼 armed 메시지가 화면에 표시된 것이 확정된다.
+ */
+function trackSpinnerActivity(state, payload) {
+    const sessionId = payload.session_id;
+    const apiMs = payload.cost?.total_api_duration_ms;
+    if (!sessionId || typeof apiMs !== "number")
+        return;
+    state.sessions ??= {};
+    const prev = state.sessions[sessionId];
+    state.sessions[sessionId] = apiMs;
+    // 오래된 세션 기록이 무한히 쌓이지 않게 상한을 둔다.
+    const ids = Object.keys(state.sessions);
+    if (ids.length > 20)
+        delete state.sessions[ids[0]];
+    if (prev === undefined || apiMs <= prev || !state.current)
+        return;
+    state.current.visibleMs = Math.min((state.current.visibleMs ?? 0) + (apiMs - prev), runtime_1.ROTATE_MS);
+}
+/**
+ * 이전 armed 메시지의 노출을 정산하고 다음 메시지를 armed한다.
+ * QUALIFIED_MS 이상 spinner가 돌았으면 유효 노출(visibleMs 포함)로 기록한다.
+ */
+function rotateSpinner(state, now) {
+    const config = (0, config_1.loadConfig)();
+    const prev = state.current;
+    if (prev && (prev.visibleMs ?? 0) >= runtime_1.QUALIFIED_MS) {
+        (0, queue_1.appendEvent)({
+            agentType: "CLAUDE",
+            type: "QUALIFIED_IMPRESSION",
+            messageId: prev.messageId,
+            visibleMs: prev.visibleMs,
+        });
+    }
+    const message = (0, picker_1.pickMessage)((0, cache_1.loadFeedMessages)(), state);
+    if (!message) {
+        (0, claude_1.armSpinnerMessage)(config, null);
+        state.current = undefined;
+        return;
+    }
+    (0, claude_1.armSpinnerMessage)(config, message);
+    state.seen[message.id] = (state.seen[message.id] ?? 0) + 1;
+    state.delivered ??= {};
+    if (!state.delivered[message.id]) {
+        (0, queue_1.appendEvent)({
+            agentType: "CLAUDE",
+            type: "DELIVERED",
+            messageId: message.id,
+        });
+        state.delivered[message.id] = 1;
+    }
+    state.current = {
+        messageId: message.id,
+        text: message.text,
+        author: message.author,
+        shownAt: now,
+        visibleMs: 0,
+    };
+}
 /**
  * Claude Code statusLine hook 진입점.
- * Ping 메시지는 spinner(spinnerVerbs)가 담당하고, statusline에는
- * 이 기기에서 작성한 최근 메시지의 도달 현황을 보여준다.
- * flush/refresh 백그라운드 트리거도 이 경로에서 돈다 (Claude 사용 중 항상 호출되므로).
+ * - spinner 회전(pool=1): ROTATE_MS마다 다음 메시지를 armed (설정 핫리로드로 즉시 반영)
+ * - 노출 측정: stdin payload의 cost 델타로 armed 메시지의 실제 표시 시간을 누적
+ * - statusline 표시: 이 기기에서 작성한 최근 메시지의 도달 현황
+ * - flush/refresh 백그라운드 트리거 (Claude 사용 중 항상 호출되므로 이 경로에서)
  */
 function runStatusline() {
+    const payload = readPayload();
     const state = (0, cache_1.loadState)();
     const now = Date.now();
-    // 300ms마다 호출되므로 상태 기록/maintenance는 1초 스로틀.
-    if (state.lastTickAt === undefined || now - state.lastTickAt > 1_000) {
+    trackSpinnerActivity(state, payload);
+    const rotateDue = !state.current || now - state.current.shownAt >= runtime_1.ROTATE_MS;
+    // 300ms마다 호출되므로 저장/maintenance는 1초 스로틀. 회전 시점에는 항상 저장.
+    const saveDue = rotateDue ||
+        state.lastTickAt === undefined ||
+        now - state.lastTickAt > 1_000;
+    if (rotateDue) {
+        rotateSpinner(state, now);
+    }
+    if (saveDue) {
         (0, runtime_1.runMaintenance)(state, now);
         state.lastTickAt = now;
         (0, cache_1.saveState)(state);

package/dist/runtime.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEED_TTL_MS = exports.FLUSH_COUNT = exports.FLUSH_INTERVAL_MS = void 0;
+exports.FEED_TTL_MS = exports.FLUSH_COUNT = exports.FLUSH_INTERVAL_MS = exports.QUALIFIED_MS = exports.ROTATE_MS = void 0;
 exports.runMaintenance = runMaintenance;
 const child_process_1 = require("child_process");
 const config_1 = require("./config");
 const cache_1 = require("./cache");
 const queue_1 = require("./queue");
+exports.ROTATE_MS = 60_000; // spinner 메시지 교체 주기 (설정 핫리로드로 즉시 반영)
+exports.QUALIFIED_MS = 3_000; // 유효 노출로 인정하는 최소 spinner 가동 시간
 exports.FLUSH_INTERVAL_MS = 60_000; // batch 전송 주기
 exports.FLUSH_COUNT = 20; // 또는 이벤트 개수 기준
 exports.FEED_TTL_MS = 5 * 60_000; // feed 캐시 갱신 주기

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinglet-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "AI가 생각하는 동안 다른 개발자의 Ping을 만나는 메시지 네트워크 — Claude Code / Codex integration",
   "license": "MIT",
   "repository": {