@chatpanel/bridge 0.10.42 → 0.11.0

package/src/engines/claude.js

@@ -49,6 +49,37 @@ const IDLE_MS = Number(process.env.CHATPANEL_CLAUDE_TIMEOUT_MS) || 180_000;
 // gated behind the agent's permission mode.
 const READONLY_TOOLS = ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch', 'TodoWrite', 'Task'];
 
+// A remote (channel) caller declares the actor's trust tier via options.reach. Unlike
+// permissionMode (which a local, already-trusted UI chooses), reach is a CEILING enforced HERE
+// at the trust boundary — a paired-but-prompt-injected phone cannot exceed its tier no matter
+// what the message says. This is the tool-authorization half of feature-f7 §7; pairing proves
+// WHO, this constrains WHAT.
+//
+// Posture (security-first): the exfil chain needs read-a-secret AND an egress to send it. We cut
+// the egress on every capped tier by dropping web tools, so even machine-wide reads can't phone
+// home; writes/shell are never granted to a capped tier.
+//   device  — conversational only: no filesystem, no web, no writes/shell.
+//   trusted — machine-wide READ (inspect your own files/projects), but NO web and NO writes/shell.
+//   any     — no cap here (operator/local console); falls through to permissionMode below.
+const CHANNEL_ALLOW = Object.freeze({
+  device: Object.freeze(['TodoWrite', 'Task']),
+  trusted: Object.freeze(['Read', 'Grep', 'Glob', 'TodoWrite', 'Task']),
+});
+// Belt-and-suspenders: the allow-list already omits these, but we also forbid them explicitly so
+// a capped turn can never reach shell, writes, or a network egress even via an MCP alias.
+const CHANNEL_DENY = Object.freeze(['Bash', 'Edit', 'Write', 'WebFetch', 'WebSearch']);
+
+/**
+ * Tool policy for a channel/remote caller. Returns { allow, deny } for a capped tier, or null
+ * when reach is absent or 'any' (no cap — the existing permissionMode logic applies). An unknown
+ * tier is treated as the MOST restrictive ('device'), never as "no cap" — fail closed.
+ */
+export function channelToolPolicy(reach) {
+  if (!reach || reach === 'any') return null;
+  const allow = CHANNEL_ALLOW[reach] || CHANNEL_ALLOW.device;
+  return { allow: [...allow], deny: [...CHANNEL_DENY] };
+}
+
 let lastReason = 'Claude Code not found.';
 let lastProbe = 0;
 let cachedOk = false;
@@ -272,10 +303,19 @@ export async function chat({ messages, system, options, images }, emit, { signal
     mcpAllow.push(...mcpConfig.allowedTools);
   }
 
+  // A remote (channel) caller's reach tier caps the toolset and OVERRIDES permissionMode: a
+  // capped tier never gets --permission-mode, so writes/shell stay denied headlessly even if a
+  // message (or a bug upstream) asked to escalate. Local callers (no reach) keep the existing
+  // permissionMode behavior unchanged.
+  const channelPolicy = channelToolPolicy(options.reach);
+  if (channelPolicy) {
+    args.push('--allowedTools', ...channelPolicy.allow, ...mcpAllow);
+    args.push('--disallowedTools', ...channelPolicy.deny);
+  }
   // Gate writes/shell behind the chosen mode; otherwise restrict to read-only
   // tools so headless runs never block on an approval prompt. The relayed browser
   // tools are always pre-allowed (the user explicitly armed them this turn).
-  if (permissionMode === 'bypassPermissions') args.push('--permission-mode', 'bypassPermissions');
+  else if (permissionMode === 'bypassPermissions') args.push('--permission-mode', 'bypassPermissions');
   else if (permissionMode === 'acceptEdits') {
     args.push('--permission-mode', 'acceptEdits');
     if (mcpAllow.length) args.push('--allowedTools', ...mcpAllow);

package/src/events/capability.js

@@ -0,0 +1,134 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/capability.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// The capability signature — one call shape a rule, a schedule, the user or a model all
+// invoke identically, through one policy path.
+//
+// `actor` is the field that makes capabilities turn-independent; it is the whole of the
+// "capabilities are not turn-shaped" principle expressed as data rather than as a
+// subsystem.
+//
+// `requirements` is what the router dispatches on: not "which model" but "what must be
+// true". {maxLatencyMs:100, deterministic:true, egress:'none'} selects class R or M on a
+// host that can realize it — or REFUSES. Silently exceeding a declared budget is the
+// failure mode this exists to prevent.
+
+import { CLASSES, EFFECTS, EGRESS, ACTOR_KINDS, SCOPE_KINDS, EventError } from './event.js';
+import { DATA_SCOPES } from './scopes.js';
+import { validateView } from './view.js';
+
+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)));
+
+/**
+ * Validate a capability DECLARATION — the static surface a reviewer, a user or an admin
+ * approves BEFORE the capability runs. Everything here is readable without executing
+ * anything, which is what makes load-time approval possible.
+ */
+export function validateCapability(c) {
+  if (!c || typeof c !== 'object') throw new EventError('SHAPE', 'capability must be an object');
+  if (!str(c.id)) throw new EventError('SHAPE', 'capability.id required');
+  if (!str(c.version)) throw new EventError('SHAPE', 'capability.version required');
+  if (!CLASSES.includes(c.class)) throw new EventError('SHAPE', `capability.class must be one of ${CLASSES}`);
+  if (!strs(c.requires)) throw new EventError('SHAPE', 'capability.requires must be string[]');
+  if (!strs(c.provides)) throw new EventError('SHAPE', 'capability.provides must be string[]');
+  if (!strs(c.reads, DATA_SCOPES)) throw new EventError('SHAPE', `capability.reads must be within ${DATA_SCOPES}`);
+  if (!strs(c.writes, DATA_SCOPES)) throw new EventError('SHAPE', `capability.writes must be within ${DATA_SCOPES}`);
+  if (!EGRESS.includes(c.egress)) throw new EventError('SHAPE', `capability.egress must be one of ${EGRESS}`);
+  if (!EFFECTS.includes(c.effects)) throw new EventError('SHAPE', `capability.effects must be one of ${EFFECTS}`);
+  if (typeof c.invoke !== 'function') throw new EventError('SHAPE', 'capability.invoke required');
+  if (typeof c.disclose !== 'function') throw new EventError('SHAPE', 'capability.disclose required');
+  if (!c.output || typeof c.output.render !== 'function') {
+    throw new EventError('SHAPE', 'capability.output.render required — canonical value and rendering are separate');
+  }
+  // A capability MAY ship its own UI. Optional, and validated against this capability so a
+  // view can never name a capability its owner isn't already allowed to call.
+  if (c.view != null) validateView(c.view, c);
+  // A class-R capability that declares egress is a contradiction: R is a determinism
+  // guarantee, and a network round-trip is not deterministic.
+  if (c.class === 'R' && c.egress !== 'none') {
+    throw new EventError('CONTRADICTION', 'class R must declare egress:none');
+  }
+  return c;
+}
+
+/**
+ * Validate an INVOCATION. Enforces the one rule that is easiest to forget and worst to
+ * miss: a capability that is not `pure` cannot be invoked without an idempotency key,
+ * because a retried delegated call would otherwise perform the side effect twice.
+ */
+export function validateInvocation(inv, capability) {
+  if (!inv || typeof inv !== 'object') throw new EventError('SHAPE', 'invocation must be an object');
+  if (!str(inv.capability)) throw new EventError('SHAPE', 'invocation.capability required');
+  if (!inv.actor || !ACTOR_KINDS.includes(inv.actor.kind) || !str(inv.actor.id)) {
+    throw new EventError('SHAPE', `invocation.actor.kind must be one of ${ACTOR_KINDS}`);
+  }
+  if (!inv.scope || !SCOPE_KINDS.includes(inv.scope.kind) || !str(inv.scope.id)) {
+    throw new EventError('SHAPE', `invocation.scope.kind must be one of ${SCOPE_KINDS}`);
+  }
+  if (!Array.isArray(inv.causes)) throw new EventError('SHAPE', 'invocation.causes must be string[]');
+  const effects = capability ? capability.effects : inv.effects;
+  if (effects && effects !== 'pure' && !str(inv.idempotencyKey)) {
+    throw new EventError('IDEMPOTENCY', `invocation of a '${effects}' capability requires an idempotencyKey`);
+  }
+  return inv;
+}
+
+/**
+ * Can this capability satisfy these requirements on this host?
+ * Returns { ok, reasons[] } — REFUSING is a valid, expected outcome.
+ *
+ * `host` supplies what it can actually realize: { realizes: {R:{maxMs},M:{maxMs},...} }.
+ * Class is intrinsic (a guarantee); latency is host-bound. Never fuse the two.
+ */
+export function canSatisfy(capability, requirements = {}, host = null) {
+  const reasons = [];
+  const { maxLatencyMs, deterministic, egress, maxCostUsd } = requirements;
+
+  if (deterministic === true && !['R', 'M'].includes(capability.class)) {
+    reasons.push(`class ${capability.class} is not deterministic`);
+  }
+  if (egress === 'none' && capability.egress !== 'none') {
+    reasons.push(`capability egresses '${capability.egress}', requirement is 'none'`);
+  }
+  if (egress === 'redacted' && capability.egress === 'delegated') {
+    reasons.push('delegated egress is not controlled, requirement is redacted');
+  }
+  if (maxLatencyMs != null && host) {
+    const realized = host.realizes && host.realizes[capability.class];
+    if (!realized) reasons.push(`host cannot realize class ${capability.class}`);
+    else if (realized.maxMs > maxLatencyMs) {
+      reasons.push(`host realizes class ${capability.class} at ~${realized.maxMs}ms, requirement is ${maxLatencyMs}ms`);
+    }
+  }
+  if (maxCostUsd != null && capability.class === 'C' && maxCostUsd <= 0) {
+    reasons.push('cloud class requires a positive cost ceiling');
+  }
+  return { ok: reasons.length === 0, reasons };
+}
+
+/**
+ * The model-facing projection — an ALLOWLIST built from exactly three fields.
+ *
+ * Never an omit-list. An omit-list leaks the next field someone adds; this cannot,
+ * because `invoke`, `effects`, `cost`, `writes` and `egress` are never copied.
+ */
+export function toModelSchema(capability) {
+  return {
+    name: capability.id,
+    description: capability.disclose().gist,
+    parameters: capability.input || { type: 'object', properties: {} },
+  };
+}
+
+/** The same allowlist over a toolset — the only supported way to build a model request. */
+export function toModelSchemas(capabilities) {
+  return capabilities.map(toModelSchema);
+}

package/src/events/event.js

@@ -0,0 +1,183 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/event.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// The event envelope — durable facts only.
+//
+// ORDER WITHOUT CLOCKS. `at` is wall time and is ADVISORY: it is shown to humans and
+// never consulted for ordering. `(host, seq)` plus `causes` are the authority, because
+// once two hosts append concurrently a timestamp is not an order (see order.js).
+//
+// EPHEMERAL STREAMS ARE NOT THIS TYPE. Market ticks, live captions and DOM mutations
+// live in an in-memory ring buffer with no id, no seq and no persistence; only the
+// windowed aggregate that entered a model request or crossed the device boundary is
+// promoted to an Event. That is structural rather than a rule to remember: durably
+// logging a caption stream is ~3 MB per meeting, ~5.5 GB/year, and there is no Event
+// type that would accept one.
+//
+// METADATA ONLY. Payloads carry Refs and counts, never content. `privacy.redacted`
+// carries how many of each entity type were redacted and never the values — a log of
+// what was redacted must not itself contain the redacted data.
+
+import { isRef } from './ref.js';
+
+export const CURRENT_VERSION = 1;
+
+/** The seven families of v1. Adding is cheap; removing is not. */
+export const EVENT_TYPES = Object.freeze({
+  turn: ['started', 'ended'],
+  // What the model was SHOWN and what it SAID. Deliberately arriving as refs, not text —
+  // see the note on the validators below.
+  assistant: ['prompted', 'message', 'reasoning'],
+  context: ['assembled', 'attached', 'expanded'],
+  capability: ['offered', 'granted', 'denied', 'activated', 'revoked', 'invoked', 'resulted'],
+  privacy: ['redacted', 'egress'],
+  policy: ['changed', 'guard_denied'],
+  data: ['created', 'updated', 'deleted'],
+  automation: ['fired', 'suppressed'],
+});
+
+export const ALL_TYPES = Object.freeze(
+  Object.entries(EVENT_TYPES).flatMap(([fam, kinds]) => kinds.map((k) => `${fam}.${k}`)),
+);
+
+// 'channel' is a message arriving from a paired external surface — Telegram, WhatsApp — that
+// drives a turn the same way a person pressing send does. It is turn-independent for the same
+// reason 'schedule' and 'agent' are: nobody is sitting in the panel when it fires, so consent
+// and reach have to be settled at pairing time, not at the keystroke. The actor.id carries the
+// surface and the sender, e.g. 'telegram:8412…'. See chatpanel-channels for the invoker.
+export const ACTOR_KINDS = Object.freeze(['user', 'rule', 'schedule', 'model', 'agent', 'channel']);
+export const SCOPE_KINDS = Object.freeze(['global', 'site', 'tab', 'session', 'agent']);
+export const CLASSES = Object.freeze(['R', 'M', 'L', 'C', 'A', 'X', 'H']);
+export const EFFECTS = Object.freeze(['pure', 'idempotent', 'replay-safe', 'non-replayable']);
+export const EGRESS = Object.freeze(['none', 'redacted', 'delegated']);
+
+export class EventError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'EventError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+const arr = (v) => Array.isArray(v);
+
+function actorOk(a) { return !!a && ACTOR_KINDS.includes(a.kind) && str(a.id); }
+function scopeOk(s) { return !!s && SCOPE_KINDS.includes(s.kind) && str(s.id); }
+
+// Per-type payload requirements. Deliberately light — enough that a malformed event
+// cannot enter an append-only log, not a full schema language.
+const PAYLOAD = {
+  'turn.started': (p) => str(p.turnId),
+  'turn.ended': (p) => str(p.turnId),
+
+  // ── assistant ─────────────────────────────────────────────────────────────
+  // "Model-visible means logged" was true of the toolset and false of the conversation:
+  // the log could say a turn happened and what it cost, but never what was asked or
+  // answered. That is the half a trajectory view needs, and the half replay cannot be
+  // checked without.
+  //
+  // CONTENT IS NEVER IN THE EVENT. Each of these carries a Ref — a content hash — and the
+  // bytes live in the blob store. Three reasons, in order of how much they matter:
+  //   1. The log stays metadata, so exporting or replicating it does not export the user's
+  //      conversations by accident. That property is the whole reason an event log is safe
+  //      to keep at all.
+  //   2. Deletion stays honest: an append-only log cannot unsay a message, but a blob can
+  //      be crypto-shredded and the ref then resolves to verified-but-unavailable. Inlined
+  //      text would make "delete my data" a lie the schema enforces forever.
+  //   3. Repeated content (the same system prompt on every turn) is stored once.
+  'assistant.prompted': (p) => str(p.turnId) && isRef(p.ref),
+  'assistant.message': (p) => str(p.turnId) && isRef(p.ref),
+  'assistant.reasoning': (p) => str(p.turnId) && isRef(p.ref),
+
+  'context.assembled': (p) => num(p.budget) && num(p.used) && !!p.parts && typeof p.parts === 'object'
+    && arr(p.resident) && p.resident.every(isRef) && num(p.reachableCount),
+  'context.attached': (p) => isRef(p.ref),
+  'context.expanded': (p) => isRef(p.ref) && num(p.tokens),
+
+  'capability.offered': (p) => str(p.capability) && str(p.reason),
+  'capability.granted': (p) => str(p.capability) && actorOk(p.actor),
+  'capability.denied': (p) => str(p.capability) && actorOk(p.actor),
+  'capability.activated': (p) => str(p.capability) && CLASSES.includes(p.classUsed),
+  'capability.revoked': (p) => str(p.capability) && str(p.cause),
+  // I3 is enforced here structurally: a non-pure invocation without a key is not a
+  // valid event, so it cannot reach the log at all.
+  'capability.invoked': (p) => str(p.capability) && actorOk(p.actor) && scopeOk(p.scope)
+    && EFFECTS.includes(p.effects) && (p.effects === 'pure' || str(p.idempotencyKey)),
+  'capability.resulted': (p) => str(p.capability) && typeof p.ok === 'boolean'
+    && CLASSES.includes(p.classUsed) && !!p.cost && num(p.cost.ms),
+
+  // counts only — never values
+  'privacy.redacted': (p) => !!p.counts && typeof p.counts === 'object'
+    && Object.values(p.counts).every(num),
+  'privacy.egress': (p) => str(p.host) && typeof p.redacted === 'boolean'
+    && typeof p.controlled === 'boolean',
+
+  'policy.changed': (p) => str(p.dial) && actorOk(p.actor) && 'from' in p && 'to' in p,
+  'policy.guard_denied': (p) => str(p.capability) && str(p.reason),
+
+  'data.created': (p) => isRef(p.ref),
+  'data.updated': (p) => isRef(p.ref),
+  'data.deleted': (p) => isRef(p.ref) && typeof p.shredded === 'boolean',
+
+  'automation.fired': (p) => str(p.ruleId) && CLASSES.includes(p.classUsed),
+  'automation.suppressed': (p) => str(p.ruleId) && str(p.reason),
+};
+
+/** Validate a durable event. Throws EventError; never mutates. */
+export function validateEvent(e) {
+  if (!e || typeof e !== 'object') throw new EventError('SHAPE', 'event must be an object');
+  if (e.v !== CURRENT_VERSION) throw new EventError('VERSION', `expected v=${CURRENT_VERSION}, got ${e.v} — upcast first`, e.v);
+  if (!str(e.id)) throw new EventError('SHAPE', 'id required');
+  if (!str(e.host)) throw new EventError('SHAPE', 'host required');
+  if (!Number.isInteger(e.seq) || e.seq < 0) throw new EventError('SHAPE', 'seq must be a non-negative integer');
+  if (!arr(e.causes) || !e.causes.every(str)) throw new EventError('SHAPE', 'causes must be string[]');
+  if (!num(e.at)) throw new EventError('SHAPE', 'at required (advisory wall clock)');
+  if (!ALL_TYPES.includes(e.type)) throw new EventError('TYPE', `unknown type ${e.type}`, e.type);
+  if (!e.payload || typeof e.payload !== 'object') throw new EventError('SHAPE', 'payload required');
+  const check = PAYLOAD[e.type];
+  if (check && !check(e.payload)) throw new EventError('PAYLOAD', `payload invalid for ${e.type}`, e.type);
+  return e;
+}
+
+export function isValidEvent(e) {
+  try { validateEvent(e); return true; } catch { return false; }
+}
+
+/**
+ * A per-host append cursor. Owns `seq` — the only monotonic thing in the system — so
+ * callers cannot skip or reuse one.
+ *
+ * `now` and `newId` are injected so tests are deterministic and so the package holds no
+ * ambient dependency on a clock or a crypto implementation.
+ */
+export function createAppender({ host, seq = 0, now = () => Date.now(), newId }) {
+  if (!str(host)) throw new EventError('SHAPE', 'host required');
+  const genId = newId || (() => globalThis.crypto.randomUUID());
+  let n = seq;
+  return {
+    get host() { return host; },
+    get seq() { return n; },
+    /** Build + validate the next event for this host. Does not persist — the caller stores it. */
+    append(type, payload, causes = []) {
+      const e = Object.freeze({
+        v: CURRENT_VERSION,
+        id: genId(),
+        host,
+        seq: n++,
+        causes: Object.freeze([...causes]),
+        at: now(),
+        type,
+        payload,
+      });
+      return validateEvent(e);
+    },
+  };
+}

package/src/events/reach.js

@@ -0,0 +1,31 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/reach.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// reach.js — how far a request may travel, on its own so it can travel alone.
+//
+// One ordered vocabulary answers "how far may this go" for three very different callers: the
+// model router ranks a model's reach against a turn's requirement, pairing gives a phone a
+// ceiling, and the bridge maps that ceiling to a toolset. Three declarations, one vocabulary,
+// or "how far may this reach" gets three answers that drift.
+//
+// A separate module rather than a constant inside router.js for the reason scopes.js exists:
+// the consumers have wildly different weights. The bridge has zero runtime dependencies by
+// design and vendors what it needs — pulling the 50 KB model router in to reach a
+// three-element array is exactly the transitive-graph mistake that split DATA_SCOPES out of
+// capability.js.
+//
+// ORDERED, least to most: a ceiling comparison is an index comparison.
+export const REACH = Object.freeze(['device', 'trusted', 'any']);
+
+/** Position in the ladder; an unknown tier ranks LOWEST, so a typo never widens reach. */
+export const reachRank = (r) => Math.max(0, REACH.indexOf(r));
+
+/** Does `have` satisfy `need`? Fails closed — an unknown `have` is treated as 'device'. */
+export function reachSatisfies(have, need) {
+  return reachRank(have) >= reachRank(need);
+}

package/src/events/ref.js

@@ -0,0 +1,60 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/ref.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// References — how the log addresses content WITHOUT copying it.
+//
+// An event records "note n_88, lines 10-40, hash H" and never the text. Content that
+// actually entered a model request is written once into a content-addressed blob store
+// keyed by hash, so the same excerpt across a hundred turns costs one copy.
+//
+// Replay resolves a Ref by hash: match => exact reconstruction; blob absent or
+// crypto-shredded => VERIFIED_BUT_UNAVAILABLE. It never silently substitutes today's
+// version of the note, because that would make replay quietly wrong instead of loudly
+// incomplete.
+
+export const REF_KINDS = Object.freeze(['note', 'meeting', 'chat', 'page', 'result', 'blob']);
+
+export const RESOLUTION = Object.freeze({
+  EXACT: 'exact',                              // blob present, hash matches
+  UNAVAILABLE: 'verified-but-unavailable',     // we know what it was; we no longer hold it
+  DRIFTED: 'drifted',                          // source still exists but its hash changed
+});
+
+/** Build a Ref. `hash` is the content hash AT CAPTURE TIME — that is the whole point. */
+export function makeRef({ kind, id, hash, range = null, stored = false }) {
+  if (!REF_KINDS.includes(kind)) throw new TypeError(`ref: unknown kind ${kind}`);
+  if (typeof id !== 'string' || !id) throw new TypeError('ref: id required');
+  if (typeof hash !== 'string' || !hash) throw new TypeError('ref: hash required');
+  const ref = { kind, id, hash };
+  if (range) {
+    if (!Number.isInteger(range.from) || !Number.isInteger(range.to) || range.to < range.from) {
+      throw new TypeError('ref: range must be {from,to} integers with to >= from');
+    }
+    ref.range = { from: range.from, to: range.to };
+  }
+  if (stored) ref.stored = true;
+  return Object.freeze(ref);
+}
+
+export function isRef(v) {
+  return !!v && typeof v === 'object'
+    && REF_KINDS.includes(v.kind)
+    && typeof v.id === 'string' && v.id.length > 0
+    && typeof v.hash === 'string' && v.hash.length > 0;
+}
+
+/**
+ * Classify what a replay can say about a Ref, given what the blob store holds now.
+ * `lookup(ref) -> { hash } | null`. Pure: the caller owns the store.
+ */
+export function resolveRef(ref, lookup) {
+  const got = lookup(ref);
+  if (!got) return { resolution: RESOLUTION.UNAVAILABLE, ref };
+  if (got.hash !== ref.hash) return { resolution: RESOLUTION.DRIFTED, ref, actualHash: got.hash };
+  return { resolution: RESOLUTION.EXACT, ref, value: got.value };
+}

package/src/events/view.js

@@ -0,0 +1,96 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/view.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// CAPABILITY VIEWS — a capability may ship its own UI, so a result can be an interactive
+// component instead of a paragraph of text.
+//
+// This is NOT the model writing HTML. That already exists (an ```html artifact runs in the
+// sandbox) and is deliberately powerless: it is untrusted text, so it can only draw. A view
+// is declared by a capability that a user or admin approved at load time, which is what
+// makes it safe to give it something a model-authored page can never have — the ability to
+// ACT, by invoking capabilities.
+//
+// The rule that keeps that safe is one line: a view may invoke only what its own capability
+// is already allowed to invoke. A calculator view can compute because its capability may; it
+// cannot read history unless that capability was granted `history` in the first place. There
+// is no path here that widens a permission — `mayInvoke` can only ever name capabilities the
+// declaring capability already lists in `requires`, and validateViewInvocation refuses
+// anything outside that set before the kernel is ever consulted.
+//
+// Pure and host-free by design: no DOM, no postMessage, no chrome.*. The client owns the
+// transport; this owns what is legal to say over it.
+
+import { EventError } from './event.js';
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+
+/**
+ * Validate a view DECLARATION. Like the rest of the capability contract this must be
+ * readable — and therefore approvable — without executing anything.
+ */
+export function validateView(view, capability = null) {
+  if (!view || typeof view !== 'object') throw new EventError('SHAPE', 'view must be an object');
+  if (!str(view.id)) throw new EventError('SHAPE', 'view.id required');
+  if (!str(view.html)) throw new EventError('SHAPE', 'view.html required — a self-contained document');
+  if (view.mayInvoke != null && !(Array.isArray(view.mayInvoke) && view.mayInvoke.every(str))) {
+    throw new EventError('SHAPE', 'view.mayInvoke must be string[]');
+  }
+  // NO PRIVILEGE ESCALATION BY DECLARATION. A view is part of its capability, so it cannot
+  // reach past it: every id it wants to call must already be in that capability's `requires`
+  // (or be the capability itself). Caught here, at approval time, rather than at call time.
+  if (capability && view.mayInvoke?.length) {
+    const allowed = new Set([capability.id, ...(capability.requires || [])]);
+    const extra = view.mayInvoke.filter((id) => !allowed.has(id));
+    if (extra.length) {
+      throw new EventError('CONTRADICTION',
+        `view.mayInvoke exceeds its capability: ${extra.join(', ')} not in requires`);
+    }
+  }
+  if (view.height != null && !(Number.isInteger(view.height) && view.height > 0 && view.height <= 2000)) {
+    throw new EventError('SHAPE', 'view.height must be a positive integer <= 2000');
+  }
+  return view;
+}
+
+/**
+ * Turn a message a VIEW sent into a capability invocation the kernel can judge — or refuse
+ * it. The view is sandboxed and its messages are untrusted input, so nothing here trusts a
+ * field: the capability id is checked against what the declaration allows, not against what
+ * the message claims to be entitled to.
+ *
+ * Returns { capability, args, callId }. Throws EventError otherwise.
+ */
+export function validateViewInvocation(msg, capability) {
+  if (!capability?.view) throw new EventError('SHAPE', 'capability declares no view');
+  if (!msg || typeof msg !== 'object') throw new EventError('SHAPE', 'view message must be an object');
+  if (!str(msg.callId)) throw new EventError('SHAPE', 'view message needs a callId to correlate its result');
+  if (!str(msg.capability)) throw new EventError('SHAPE', 'view message must name a capability');
+
+  const allowed = new Set([capability.id, ...(capability.view.mayInvoke || [])]);
+  if (!allowed.has(msg.capability)) {
+    // The important refusal. A compromised or buggy view asking for something else stops
+    // here, before any kernel guard has to have an opinion about it.
+    throw new EventError('DENIED',
+      `view of "${capability.id}" may not invoke "${msg.capability}"`);
+  }
+  if (msg.args != null && (typeof msg.args !== 'object' || Array.isArray(msg.args))) {
+    throw new EventError('SHAPE', 'view invocation args must be an object');
+  }
+  return { capability: msg.capability, args: msg.args || {}, callId: msg.callId };
+}
+
+/**
+ * The state a view is mounted with, as it appears on a capability RESULT. Kept separate from
+ * the canonical value: `value` is what the capability computed and what everything else
+ * reasons about; `view`/`state` are only how it is shown. A host that cannot render views
+ * ignores these two fields and still has the whole answer.
+ */
+export function viewResult(value, capability, state = null) {
+  if (!capability?.view) return { value };
+  return { value, view: capability.view.id, state: state ?? value };
+}

package/src/pii/index.js

@@ -0,0 +1,29 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-pii/index.js (npm @chatpanel/pii).
+// Edit there, then run: npm run sync:pii
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// chatpanel-pii — the canonical ChatPanel privacy engine. Single source of truth
+// for reversible PII redaction + pseudonymization, shared by the extension, the
+// gateway, and the bridge. Pure + dependency-free ESM.
+//
+//   import { createVault, redactText, restoreText, detectEntities } from 'chatpanel-pii';
+//
+// Submodules are also importable directly:
+//   'chatpanel-pii/pii-redact.js'   deterministic redact/restore + vault
+//   'chatpanel-pii/pii-detect.js'   local NER / LLM entity detection
+//   'chatpanel-pii/pipeline.js'     pure turn orchestration + tier/scope selection
+//   'chatpanel-pii/tool-rank.js'    deterministic tool narrowing (auto mode)
+//   'chatpanel-pii/sanitize.js'     Unicode de-steganography (strip invisible/format chars)
+//   'chatpanel-pii/net.js'          SSRF host classifier + outbound-URL guard
+
+export * from './pii-redact.js';
+export * from './pii-detect.js';
+export * from './pipeline.js';
+export * from './tool-rank.js';
+export * from './tool-harness.js';
+export * from './sanitize.js';
+export * from './net.js';