@chatpanel/events 0.6.0 → 0.8.0

package/capability.js

@@ -11,8 +11,9 @@
 // failure mode this exists to prevent.
 
 import { CLASSES, EFFECTS, EGRESS, ACTOR_KINDS, SCOPE_KINDS, EventError } from './event.js';
+import { DATA_SCOPES } from './scopes.js';
 
-export const DATA_SCOPES = Object.freeze(['notes', 'meetings', 'chats', 'page', 'files', 'net']);
+export { DATA_SCOPES } from './scopes.js';
 
 const str = (v) => typeof v === 'string' && v.length > 0;
 const strs = (v, allowed = null) => Array.isArray(v) && v.every((x) => str(x) && (!allowed || allowed.includes(x)));

package/index.js

@@ -19,7 +19,7 @@ export { REF_KINDS, RESOLUTION, makeRef, isRef, resolveRef } from './ref.js';
 export { linearize, compareEvents, causesAreWellFormed } from './order.js';
 export { UPCASTERS, upcast, upcastAll } from './upcast.js';
 export {
-  DATA_SCOPES, validateCapability, validateInvocation, canSatisfy,
+  validateCapability, validateInvocation, canSatisfy,
   toModelSchema, toModelSchemas,
 } from './capability.js';
 export { checkInvariants, INVARIANTS } from './invariants.js';
@@ -43,6 +43,8 @@ export { createManifest, ManifestError, SOURCES } from './manifest.js';
 export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL } from './kernel.js';
 export { replay, formatReport, parseJsonl, toJsonl } from './harness.js';
 export { compileQuery, findMatches, matchIndexFor, expandReplacement, replaceMatch, replaceAll, replaceAllInRange, MAX_MATCHES } from './text-search.js';
+export { DATA_SCOPES } from './scopes.js';
+export { SOURCE_TRUST, SkillSourceError, defineSkillSource, createSkillSourceRegistry } from './skill-sources.js';
 export { SKILL_MANIFEST_VERSION, SKILL_CONTEXTS, SKILL_HISTORY_SCOPES, SKILL_MCP_MODES, SKILL_TRUST, SKILL_FILE_KINDS, SKILL_UPCASTERS, SkillManifestError, isSafeSkillPath, originOf, trustOf, skillFiles, needsBridge, declaredAccess, originLabel, sameSkillOrigin, skillIsStale, validateSkill, upcastSkill, upcastSkills, normalizeSkill } from './skill-manifest.js';
 export { SKILL_VARS, SKILL_VAR_NAMES, skillVar, skillVarPattern, parseSkillVars, lintSkillPrompt, suggestSkillVar, substituteSkillVars, skillVarGuidance, SkillVarError } from './skill-vars.js';
 export { outlineOf, parseListItem, continueList, indentSelection, toggleWrap, toggleLinePrefix, toggleTask, toggleLink, docStats, selectionStats } from './markdown-authoring.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
@@ -24,8 +24,10 @@
     "./route-graph.js": "./route-graph.js",
     "./router.js": "./router.js",
     "./rules.js": "./rules.js",
+    "./scopes.js": "./scopes.js",
     "./search-engines.js": "./search-engines.js",
     "./skill-manifest.js": "./skill-manifest.js",
+    "./skill-sources.js": "./skill-sources.js",
     "./skill-vars.js": "./skill-vars.js",
     "./sources-retrieval.js": "./sources-retrieval.js",
     "./sources.js": "./sources.js",
@@ -58,8 +60,10 @@
     "route-graph.js",
     "router.js",
     "rules.js",
+    "scopes.js",
     "search-engines.js",
     "skill-manifest.js",
+    "skill-sources.js",
     "skill-vars.js",
     "sources-retrieval.js",
     "sources.js",

package/scopes.js

@@ -0,0 +1,12 @@
+// scopes.js — the data-scope vocabulary, on its own so it can travel alone.
+//
+// One list names what anything in ChatPanel may touch. Capabilities declare `reads`
+// and `writes` from it, sources declare `reads`, and a skill package declares `reads`
+// — three declarations, one vocabulary, or "what may this reach" gets three answers.
+//
+// It is a separate module rather than a constant inside capability.js because the
+// consumers have very different weights. The bridge vendors the skill contract and has
+// zero runtime dependencies by design; pulling the capability machinery and the event
+// schema behind it to reach a five-element array would be the transitive-graph mistake
+// the extension's first-paint budget exists to prevent, one repo over.
+export const DATA_SCOPES = Object.freeze(['notes', 'meetings', 'chats', 'page', 'files', 'net']);

package/skill-manifest.js

@@ -25,7 +25,7 @@
 // default, and the upcast chain exists from the start so adding v3 does not mean
 // rewriting every reader.
 
-import { DATA_SCOPES } from './capability.js';
+import { DATA_SCOPES } from './scopes.js';
 
 export class SkillManifestError extends Error {
   constructor(code, message) { super(message); this.name = 'SkillManifestError'; this.code = code; }

package/skill-sources.js

@@ -0,0 +1,162 @@
+// skill-sources.js — where skills can come from, as a contract instead of a panel.
+//
+// The instinct when adding "browse a skills hub" is to build the panel the MCP registry
+// bar was built as: one file that knows one API. That is how `history-rag.js` came to
+// hand-write three loaders, and how adding a fourth meant editing four files. The places
+// skills come from are already several — a local bridge, skills.sh, GitHub taps, a site
+// publishing /.well-known/skills, and whatever appears next — and they differ only in how
+// three functions are implemented.
+//
+// So a source is a registration. Register one and browsing, searching and installing gain
+// it at once, because each consumes the registry rather than a list.
+//
+// A SOURCE IS A CAPABILITY. `reads` is the declared access statement (P10) and `trust` is
+// the level everything it produces inherits — a source cannot promote its own skills, and
+// nothing fetched is ever `built-in`.
+//
+// ISOLATION IS THE POINT. One hub being down, slow, or returning garbage must cost that
+// hub's section of the results and nothing else. A registry whose failure mode is "no
+// skills anywhere" would be worse than the hardcoded list it replaced.
+//
+// WHAT IS SHARED IS THE CONTRACT, NOT THE SOURCE. Searching is pure orchestration and
+// lives here; the fetch a real source performs needs a platform — the extension's
+// `secureFetch`, the bridge's Node http, a mobile client's own stack — and is injected at
+// registration, the same split `adapters.js` makes for execution.
+
+import { DATA_SCOPES } from './scopes.js';
+
+export class SkillSourceError extends Error {
+  constructor(code, message) { super(message); this.name = 'SkillSourceError'; this.code = code; }
+}
+
+/**
+ * Trust a source confers on everything it produces. There is no `built-in` here on
+ * purpose: only skills compiled into the product are ours, and no registration can claim
+ * that. `local` is a source on this machine (the bridge's store); `community` is anything
+ * off the network.
+ */
+export const SOURCE_TRUST = Object.freeze(['local', 'community']);
+
+/**
+ * Declare a source.
+ *
+ * @param id       stable id; also the `origin.source` stamped on everything it yields
+ * @param label    human name, for the picker and for provenance
+ * @param trust    'local' | 'community' — inherited, never self-assigned per skill
+ * @param reads    declared access, e.g. ['net'] for a hub, [] for the local bridge
+ * @param list     ({ query, cursor }) -> { items, nextCursor? }. `items` are RECORDS
+ *                 (name + description + files), never bodies — level 0 of the ladder
+ * @param read     (id) -> a full record including its prompt. Level 1
+ * @param readFile (id, path) -> { path, text }. Level 2, optional: a source with no
+ *                 packages simply omits it
+ * @param available () -> boolean|Promise<boolean>. A source that cannot answer right now
+ *                 (bridge down, no network) is ABSENT rather than broken — the difference
+ *                 between "nothing here" and an error the user must interpret
+ */
+export function defineSkillSource({
+  id, label, trust = 'community', reads = [], list, read, readFile = null, available = null,
+}) {
+  if (!id || typeof id !== 'string') throw new SkillSourceError('BAD_SOURCE', 'source.id required');
+  if (!SOURCE_TRUST.includes(trust)) {
+    throw new SkillSourceError('BAD_SOURCE', `source '${id}': trust must be one of ${SOURCE_TRUST}`);
+  }
+  if (!Array.isArray(reads) || !reads.every((r) => DATA_SCOPES.includes(r))) {
+    throw new SkillSourceError('BAD_SOURCE', `source '${id}': reads must be within ${DATA_SCOPES}`);
+  }
+  if (typeof list !== 'function') throw new SkillSourceError('BAD_SOURCE', `source '${id}': list() required`);
+  if (typeof read !== 'function') throw new SkillSourceError('BAD_SOURCE', `source '${id}': read() required`);
+  return Object.freeze({
+    id,
+    label: label || id,
+    trust,
+    reads: Object.freeze([...reads]),
+    list,
+    read,
+    readFile: typeof readFile === 'function' ? readFile : null,
+    available: typeof available === 'function' ? available : () => true,
+  });
+}
+
+/** The registry a host binds sources into. Insertion-ordered, so results are stable. */
+export function createSkillSourceRegistry() {
+  const sources = new Map();
+  return {
+    /** Register a source. Returns its remover, so registration is revertible (P15). */
+    add(source) {
+      if (sources.has(source.id)) throw new SkillSourceError('DUPLICATE', `source '${source.id}' already registered`);
+      sources.set(source.id, source);
+      return () => sources.delete(source.id);
+    },
+
+    list() { return [...sources.values()]; },
+    get(id) { return sources.get(id) || null; },
+    has(id) { return sources.has(id); },
+
+    /**
+     * Ask every available source at once.
+     *
+     * Returns one section PER SOURCE rather than a merged list: a merged list would have
+     * to rank across hubs that share no scoring, and it would hide which source an entry
+     * came from at exactly the moment that matters. A source that throws yields an
+     * `error` section and never rejects the call.
+     */
+    async search({ query = '', cursor = '', only = null } = {}) {
+      const wanted = [...sources.values()].filter((s) => !only || only.includes(s.id));
+      return Promise.all(wanted.map(async (source) => {
+        try {
+          if (!(await source.available())) return { source: source.id, label: source.label, items: [], absent: true };
+          const page = (await source.list({ query, cursor })) || {};
+          const items = Array.isArray(page.items) ? page.items : [];
+          return {
+            source: source.id,
+            label: source.label,
+            trust: source.trust,
+            // Provenance is stamped HERE, from the registration — a source that could
+            // label its own results could label them as something more trusted.
+            items: items.map((skill) => stampOrigin(skill, source)),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+          };
+        } catch (e) {
+          return { source: source.id, label: source.label, items: [], error: String(e?.message || e) };
+        }
+      }));
+    },
+
+    /** One skill, body included, with provenance stamped the same way. */
+    async read(sourceId, skillId) {
+      const source = sources.get(sourceId);
+      if (!source) throw new SkillSourceError('UNKNOWN_SOURCE', `no source '${sourceId}'`);
+      const skill = await source.read(skillId);
+      return skill ? stampOrigin(skill, source) : null;
+    },
+
+    async readFile(sourceId, skillId, path) {
+      const source = sources.get(sourceId);
+      if (!source) throw new SkillSourceError('UNKNOWN_SOURCE', `no source '${sourceId}'`);
+      if (!source.readFile) throw new SkillSourceError('NO_FILES', `source '${sourceId}' has no package files`);
+      return source.readFile(skillId, path);
+    },
+  };
+}
+
+/**
+ * Stamp where a record came from, overriding whatever it claimed.
+ *
+ * A skill arriving from a source does not get to say which source it came from, or that
+ * it is ours: `builtin` is cleared here, and `trustOf()` then derives `community` from the
+ * presence of an origin. The record's own `origin.hash` survives — that is the content
+ * identity the scanner and the update check compare against, and only the fetcher knows it.
+ */
+function stampOrigin(skill, source) {
+  if (!skill || typeof skill !== 'object') return skill;
+  const claimed = skill.origin && typeof skill.origin === 'object' ? skill.origin : {};
+  return {
+    ...skill,
+    builtin: false,
+    origin: {
+      ...claimed,
+      source: source.id,
+      id: String(claimed.id || skill.id || ''),
+    },
+  };
+}