@tinoy/pi-canon 0.3.0 → 0.5.0

package/README.md

@@ -16,7 +16,8 @@ pi install npm:@tinoy/pi-canon
 - **Tools** — `canon_add`, `canon_remove`, `canon_edit`, `canon_category`.
 - **Commands** — `/canon` (list, add, remove, edit, category management) and `/canon-dump`.
 - **Injection** — the block is appended at `before_agent_start` and re-normalized on every provider request, so a run started by an injected message carries the same bytes as an interactive prompt.
-- **Peer notices** — entry changes are broadcast over the pi-intercom bus (namespace `canon`); receivers match the entry scope against their own model and audience.
+- **Category headings** — a category sub-heading inside a scope group prints the store id after the word `category` (`#### Behavioural Preferences [category 1cg5lr]`), which is the same id a `canon_add` refusal lists; the word keeps it from reading as an entry handle, which the block renders as `[1i15c2]`. Uncategorized entries carry no id, and a scope group holding a single category stays flat with no sub-heading.
+- **Peer notices** — entry changes are published over the `ipc` transport's bus (namespace `canon`); receivers match the entry scope against their own model and audience.
 - **Tail sections** — another extension contributes prompt text through the `canon:section` event; its ids are published on `canon:sections`.
 
 ## Exports

package/index.ts

@@ -14,7 +14,7 @@
  * changes via canon notices (and the user's /canon-dump).
  * Edited at runtime via canon_add / canon_remove / canon_edit (plus
  * the /canon and /canon-dump commands). Changes are broadcast to peer sessions
- * over the pi-intercom extension bus (namespace "canon"); each receiver matches
+ * over the `ipc` transport's extension bus (namespace "canon"); each receiver matches
  * the entry scope against its own model + audience before showing a notice.
  *
  * Replaces APPEND_SYSTEM.md (global/parent) and FLASH.md (global/subagent).
@@ -31,11 +31,13 @@
  *
  * Store: ~/.pi/agent/canon/canon.json — { entries: [{id, text, model, audience, reason?, category?}], categories: [{id, title, description?}] }
  * Categories are un-ordered; entries reference them by id. They render as sub-headings
- * inside scope groups (store insertion order), with uncategorized entries last.
+ * inside scope groups (store insertion order), with uncategorized entries last, and
+ * each heading carries the store's own id after the word `category`
+ * (`#### Behavioural Preferences [category 1cg5lr]`) — the word keeps the category id
+ * from reading as an entry handle, which the block renders as `[1i15c2]`.
  * canon_add REQUIRES a category and canon_edit can only CHANGE one: every refusal
- * lists the valid ids with their titles, so a retry costs no lookup call. The
- * injected block renders titles only, so the refusal is also the only place an id
- * reaches the model. The store validator counts entries that are uncategorized or
+ * lists the valid ids with their titles, so a retry costs no lookup call. The store
+ * validator counts entries that are uncategorized or
  * carry a category id the store no longer holds (both render as Uncategorized) and
  * reports the count to the hook log once per distinct state.
  * Both the injected block and /canon-dump group entries under scope headers (model ×
@@ -339,7 +341,8 @@ function scopeGroups(entries: CanonEntry[]): ScopeGroup[] {
 	);
 }
 
-/** Render the injected block: header, scope groups, category sub-headings inside. */
+/** Render the injected block: header, scope groups, category sub-headings inside, each
+ *  naming its store category id. */
 function render(
 	store: Store,
 	model: string,
@@ -367,7 +370,7 @@ function render(
 		// only show category sub-headings when a scope group actually splits
 		const showCatHeadings = orderedCats.length + (uncat.length ? 1 : 0) >= 2;
 		for (const c of orderedCats) {
-			if (showCatHeadings) block += `\n\n#### ${c.title}`;
+			if (showCatHeadings) block += `\n\n#### ${c.title} [category ${c.id}]`;
 			block += `\n${buckets
 				.get(c.id)!
 				.map((e) => `[${e.id}] ${e.text}`)
@@ -417,11 +420,11 @@ function renderDump(
 /**
  * Resolve a category reference to its id.
  *
- * The injected canon block shows category TITLES as sub-headings (`#### System
- * Knowledge`) and never shows an id, so a model naturally passes the title back to
- * canon_add — refusing that costs a call and teaches nothing. An exact id wins; a
- * title matches case-insensitively; anything else fails with a short reason that
- * the caller turns into a refusal.
+ * The block prints each heading as its title followed by the store id
+ * (`#### <title> [category <id>]`), and a model that copies the heading copies the
+ * title most of the time, so both forms are accepted: an exact id wins, a title
+ * matches case-insensitively, and anything else fails with a short reason that the
+ * caller turns into a refusal.
  */
 function lookupCategory(
 	store: Store,
@@ -447,10 +450,8 @@ function lookupCategory(
 
 /**
  * The refusal for every rejected category value: what failed, then every valid id
- * with its title so a retry needs no lookup call of its own, then the one
- * instruction that answers it. Terse by construction — it lands in a model's
- * context, and the listing is the only place a category id is ever shown (the
- * injected block renders titles).
+ * with its title, then the one instruction that answers it. Terse by construction —
+ * it lands in a model's context.
  */
 function categoryRefusal(
 	store: Store,
@@ -713,8 +714,8 @@ export default function (pi: ExtensionAPI) {
 
 	// Best-effort peer notice: the store write has already landed when this runs,
 	// so EVERY failure mode of the channel call is swallowed here and logged:
-	//   - pi-intercom 0.12.1's channel.publish is SYNCHRONOUS and throws
-	//     "Intercom is not connected" when the broker client is down;
+	//   - the channel's publish may throw SYNCHRONOUSLY when the transport is
+	//     down, and returns void, so there is no promise to catch;
 	//   - it returns void, so .catch must only ever be reached through the
 	//     optional call (chaining it directly was the TypeError that escaped);
 	//   - a promise-returning build rejects instead of throwing — the guarded
@@ -747,7 +748,7 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
-	// ---------- intercom channel (mirrors the intercom-broadcast package) ----------
+	// ---------- the bus channel (mirrors the ipc package's registration) ----------
 
 	const registration: CanonRegistration = {
 		namespace: NAMESPACE,
@@ -792,7 +793,7 @@ export default function (pi: ExtensionAPI) {
 		pi.events.emit("intercom:extension-register", registration);
 	}
 
-	// pi-intercom may load after this extension; re-emit once its registry is
+	// The registrar may load after this extension; re-emit once the registry is
 	// reported ready. First successful registration wins (duplicate namespace
 	// is rejected, not thrown).
 	pi.events.on("intercom:extension-registry-ready", () => {
@@ -1243,7 +1244,7 @@ export default function (pi: ExtensionAPI) {
 		name: "canon_category",
 		label: "Manage canon categories",
 		description:
-			"Manage canon categories: op add (title, description?) creates one; op edit (id, title?, description?) updates it; op remove (id) deletes it and detaches its entries to Uncategorized; op list shows all. Categories are un-ordered and render as sub-headings inside scope groups in store insertion order.",
+			"Manage canon categories: op add (title, description?) creates one; op edit (id, title?, description?) updates it; op remove (id) deletes it and detaches its entries to Uncategorized; op list shows all. Categories are un-ordered and render as sub-headings inside scope groups in store insertion order, each heading naming the category id (`#### Tools [category u3q9pr]`).",
 		promptSnippet: "Manage canon categories (add/edit/remove/list)",
 		parameters: Type.Object({
 			op: Type.String({ description: "add | edit | remove | list" }),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tinoy/pi-canon",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "Durable system-prompt rules for pi: an on-disk canon store, its tools, and the /canon commands.",
 	"license": "MIT",
 	"repository": {