@lmzhen/dsh-skill-usage 0.1.0 → 0.2.0-rc.1

package/README.md

@@ -2,6 +2,14 @@
 
 Skill usage telemetry service
 
+## Telemetry sources
+
+`record(name, kind)` is the write API (`use` / `view` / `patch`). Reads are
+observed automatically: the service listens for `session/event` `tool/call`
+records of the read tools (`skill`, `skill_load`) and bumps `view` on
+EXISTING records only — an arbitrary read never mints a usage record
+(records are authored by skill creation, patching, or curator seeding).
+
 ## Model Experience
 
 ### Indirect model surface

package/lib/index.js

@@ -1,21 +1,110 @@
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { bumpPatch, bumpUse, bumpView, evolutionIoAdapter, getRecord, loadUsage, markAgentCreated, mutateUsage, skillsRoot } from "@lmzhen/dsh-evolution-core";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { appendEvolutionEvent, bumpPatch, bumpUse, bumpView, eventsFile, evolutionIoAdapter, getRecord, loadUsage, markAgentCreated, mutateUsage, skillsRoot } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Skill usage telemetry service for the evolution family.
 * @module @lmzhen/dsh-skill-usage
 */
+/**
+* Read tool names -> usage kind. The single declarative classification table
+* for read-side observation (A2): any tool listed here records a `view` when
+* its call arguments name a skill.
+*/
+const READ_TOOL_KIND = {
+	skill: "view",
+	skill_load: "view"
+};
+/**
+* Skill name from a tool/call arguments payload (A2, mirrors
+* evolution-review's collectReadSkillNames): JSON strings are re-parsed and
+* `name` wins over `skill`. Empty when unparseable or anonymous.
+*/
+function skillNameFromToolCall(raw) {
+	let parsed = {};
+	if (typeof raw === "string") try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return "";
+	}
+	else if (raw && typeof raw === "object") parsed = raw;
+	return typeof parsed.name === "string" ? parsed.name : typeof parsed.skill === "string" ? parsed.skill : "";
+}
+/** Cumulative library-wide usage totals (C observation-window event counts). */
+function usageTotals(map) {
+	let views = 0;
+	let use = 0;
+	let patches = 0;
+	for (const record of map.values()) {
+		views += record.view_count;
+		use += record.use_count;
+		patches += record.patch_count;
+	}
+	return {
+		skills: map.size,
+		views,
+		use,
+		patches
+	};
+}
 var SkillUsageRegistry = class extends Service {
 	static inject = ["evolutionIo"];
-	static Config = z.object({ root: z.string().default("") });
+	static Config = z.object({
+		root: z.string().default(""),
+		eventsHome: z.string().default("")
+	});
 	root;
+	eventsHome;
 	io;
 	chain = Promise.resolve();
 	constructor(ctx, config = {}) {
 		super(ctx, "skillUsage");
 		this.root = config.root || skillsRoot();
+		this.eventsHome = config.eventsHome || process.env.DSH_HOME || join(homedir(), ".dsh");
 		this.io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
+		ctx.on("session/event", (_session, event) => {
+			if (event.type !== "tool/call") return;
+			if (!READ_TOOL_KIND[event.data.name]) return;
+			const name = skillNameFromToolCall(event.data.arguments);
+			if (!name) return;
+			this.observeRead(name).catch(() => {});
+		});
+	}
+	/**
+	* Read-side telemetry (A2): bump the view counter for an EXISTING record
+	* only. Creation-free by design — otherwise an arbitrary read mints a
+	* record, and "patched many times, reads zero" (the write-ghost signal)
+	* stays computable only while records exist from authorship paths.
+	*
+	* Observation window (C): the FIRST observed read library-wide opens the
+	* window — one `type:'usage'` event is appended to the evolution timeline
+	* (best-effort; the usage sidecar stays the truth and never fails the read
+	* path). Post-A2 deployments treat `view_count` as trustworthy only after
+	* that anchor exists (curator gates churn on `usageObserved()`).
+	*/
+	observeRead(name) {
+		return this.mutate(async (map) => {
+			if (!map.has(name)) return;
+			const viewsBefore = usageTotals(map).views;
+			bumpView(map, name, /* @__PURE__ */ new Date());
+			if (viewsBefore === 0) await this.appendUsageWindowEvent(map);
+		});
+	}
+	/** Append the observation-window anchor event; best-effort, never fails the observation. */
+	async appendUsageWindowEvent(map) {
+		try {
+			const at = (/* @__PURE__ */ new Date()).toISOString();
+			await appendEvolutionEvent(this.io, eventsFile(this.eventsHome), {
+				type: "usage",
+				kind: "skill",
+				source: "observation",
+				note: "observation window opened",
+				counts: usageTotals(map),
+				window: { opened: at }
+			});
+		} catch {}
 	}
 	/**
 	* Serialize read-modify-write cycles so concurrent record calls never lose

package/lib/types/index.d.ts

@@ -12,14 +12,32 @@ declare module '@deepseek-ai/cordis' {
 }
 export interface Config {
     root?: string;
+    /** Home for the evolution event timeline (`<eventsHome>/evolution/events.json`); defaults to DSH_HOME or ~/.dsh. */
+    eventsHome?: string;
 }
 export declare class SkillUsageRegistry extends Service {
     static inject: string[];
     static Config: Schema<Config>;
     readonly root: string;
+    private readonly eventsHome;
     private readonly io;
     private chain;
     constructor(ctx: Context, config?: Config);
+    /**
+     * Read-side telemetry (A2): bump the view counter for an EXISTING record
+     * only. Creation-free by design — otherwise an arbitrary read mints a
+     * record, and "patched many times, reads zero" (the write-ghost signal)
+     * stays computable only while records exist from authorship paths.
+     *
+     * Observation window (C): the FIRST observed read library-wide opens the
+     * window — one `type:'usage'` event is appended to the evolution timeline
+     * (best-effort; the usage sidecar stays the truth and never fails the read
+     * path). Post-A2 deployments treat `view_count` as trustworthy only after
+     * that anchor exists (curator gates churn on `usageObserved()`).
+     */
+    private observeRead;
+    /** Append the observation-window anchor event; best-effort, never fails the observation. */
+    private appendUsageWindowEvent;
     /**
      * Serialize read-modify-write cycles so concurrent record calls never lose
      * updates, then run each cycle as ONE atomic transact (rc.50 P2-2): the map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-skill-usage",
   "description": "Skill usage telemetry service (community build)",
-  "version": "0.1.0",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -33,16 +33,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.1.0"
+    "@lmzhen/dsh-evolution-core": "^0.2.0-rc.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.1.0"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@lmzhen/dsh-evolution-io": "^0.2.0-rc.1"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-core": "^0.1.0",
-    "@lmzhen/dsh-evolution-io": "^0.1.0"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@lmzhen/dsh-evolution-core": "^0.2.0-rc.1",
+    "@lmzhen/dsh-evolution-io": "^0.2.0-rc.1"
   }
 }