@animalabs/agent-framework 0.31.0 → 0.33.0

package/src/gate/wake-onboarding.ts

@@ -0,0 +1,309 @@
+/**
+ * Wake onboarding: an MCPL server whose events the agent's wake rules never
+ * decided about.
+ *
+ * A server's events are often skipped by a rule written for something else —
+ * a catch-all with no `source` (a Discord-era `discord-ambient`) or the gate's
+ * default — so a game that waits on the agent's move, or a message addressed
+ * to it, stalls without anyone having chosen that. MCPL RFC-001 §5 lets a
+ * server suggest how its tagged events should be treated, and §5.2 forbids a
+ * host from applying suggestions it was not told to apply. This module is the
+ * missing step between the two: the host notices the first undecided event
+ * from a server, offers the agent that server's suggestions once, and records
+ * the agent's answer — accepted (all of them or some) or declined — keyed to
+ * the server's declared ontology, so it asks again only when the ontology
+ * changes.
+ *
+ * An event is *undecided* when the gate let it go by without waking
+ * (`defer`/`skip`) by its default, or by a rule that names neither the event's
+ * source nor its channel nor any of its tags. A rule that does — Linn's
+ * `touche-quiet`, a channel's debounce — is a decision, and this module leaves
+ * it alone. So does the gate's sleep, gate.js, and every rule that wakes later
+ * (debounce, judge, a rate limit or sampler).
+ *
+ * Pure functions here; the framework wires the notice, the wake and the tools.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { stableHash } from '../stable-hash.js';
+import { firstCatchAll, ruleDecides } from './rule-scope.js';
+import type { GateBehavior, GateDecision, GatePolicy } from './types.js';
+
+/**
+ * Tags that say an event is addressed to the agent or waiting on it (MCPL
+ * RFC-001 `chat:addressed`, RFC-014 `surface:turn`/`surface:alert`; not
+ * `surface:invite`, which only suggests). The first undecided event carrying
+ * one wakes the agent to decide; any other undecided event leaves its offer
+ * for the agent's next turn.
+ */
+export const ATTENTION_TAGS: readonly string[] = ['chat:addressed', 'surface:turn', 'surface:alert'];
+
+/** Accepted rules are named `suggested:<server>:<n>`: the name is the attribution. */
+export const SUGGESTED_RULE_PREFIX = 'suggested:';
+export const suggestedRuleName = (server: string, n: number): string => `${SUGGESTED_RULE_PREFIX}${server}:${n}`;
+/** Exactly `suggested:<server>:<n>`: a server id that another extends (`games`, `games:beta`) never claims the other's rules. */
+export const isSuggestedRuleOf = (name: string, server: string): boolean =>
+  name.startsWith(`${SUGGESTED_RULE_PREFIX}${server}:`) && /^\d+$/.test(name.slice(SUGGESTED_RULE_PREFIX.length + server.length + 1));
+
+/** One of a server's suggestions as the host offers it: the server's words and the rule it becomes. */
+export interface OfferedRule {
+  /** 1-based: the number `wake_accept_suggestions` takes it by. */
+  n: number;
+  /** The feature set that declared it; empty for the host's own fallback. */
+  featureSet: string;
+  match: { tagsAny?: string[]; tagsAll?: string[]; tagsNone?: string[] };
+  /** The gate behavior the suggestion becomes. */
+  behavior: GateBehavior;
+  /** The server's own word for it (`immediate`, `{ debounce: 60000 }`, …). */
+  said: unknown;
+  /** The server's account of what the rule is for and what declining costs. */
+  rationale?: string;
+  /** The host wrote it: the server suggested nothing it could use. */
+  fallback?: boolean;
+}
+
+export interface ServerOffer {
+  server: string;
+  /** What the decision is about: a digest of the server's declared ontologies ('none' without one). */
+  digest: string;
+  rules: OfferedRule[];
+  /** Descriptions the server gave of the tags its rules name. */
+  tagDescriptions: Record<string, string>;
+  /** Suggestions in the declaration the host could not translate, as given. */
+  untranslated: unknown[];
+}
+
+type Ontology = {
+  tags?: Record<string, unknown>;
+  suggestedTreatment?: unknown;
+  /** RFC-001 revision 1's name for suggestedTreatment; still accepted. */
+  defaultTreatment?: unknown;
+};
+
+const DEBOUNCE_MIN_MS = 100;
+const DEBOUNCE_MAX_MS = 300_000;
+const THROTTLE_DEFAULT_MS = 60_000;
+
+/**
+ * A suggested behavior (RFC-001 §6's vocabulary, or the gate's own names) as a
+ * gate behavior; null for one with no faithful translation.
+ */
+export function translateBehavior(said: unknown): GateBehavior | null {
+  if (said === 'immediate' || said === 'always') return 'always';
+  if (said === 'mute' || said === 'defer' || said === 'skip') return 'defer';
+  if (said === 'throttle') return { rate_limit: { tokens: 1, refillIntervalMs: THROTTLE_DEFAULT_MS } };
+  if (said && typeof said === 'object' && !Array.isArray(said)) {
+    const o = said as Record<string, unknown>;
+    if (typeof o.debounce === 'number' && Number.isFinite(o.debounce)) {
+      return { debounce: Math.min(DEBOUNCE_MAX_MS, Math.max(DEBOUNCE_MIN_MS, Math.round(o.debounce))) };
+    }
+    const perMs = (o.throttle as Record<string, unknown> | undefined)?.perMs;
+    if (typeof perMs === 'number' && perMs > 0) return { rate_limit: { tokens: 1, refillIntervalMs: Math.round(perMs) } };
+    const every = (o.sample as Record<string, unknown> | undefined)?.every;
+    if (typeof every === 'number' && Number.isInteger(every) && every > 0) return { passive_sample: { every } };
+  }
+  return null;
+}
+
+const tagList = (v: unknown): string[] | undefined => {
+  if (!Array.isArray(v)) return undefined;
+  const tags = v.filter((t): t is string => typeof t === 'string' && t.length > 0);
+  return tags.length > 0 ? tags : undefined;
+};
+
+/**
+ * A server's suggestions from its declared feature sets (null: none declared).
+ * Feature sets in name order; in each, its ordered rules as declared, then
+ * per-tag suggestions no ordered rule already makes, by tag. A server that suggests nothing the host can
+ * use gets one host-written rule: wake for its events tagged as addressed to
+ * the agent or waiting on it, nothing else.
+ */
+export function offerFor(server: string, declared: Record<string, { tagOntology?: unknown }> | null): ServerOffer {
+  const rules: OfferedRule[] = [];
+  const tagDescriptions: Record<string, string> = {};
+  const untranslated: unknown[] = [];
+  const ontologies: Record<string, unknown> = {};
+  const seen = new Set<string>();
+  const add = (featureSet: string, match: OfferedRule['match'], said: unknown, rationale?: unknown) => {
+    const behavior = translateBehavior(said);
+    if (!behavior) { untranslated.push({ featureSet, ...match, behavior: said }); return; }
+    const key = stableHash({ match, behavior });
+    if (seen.has(key)) return;
+    seen.add(key);
+    rules.push({
+      n: rules.length + 1, featureSet, match, behavior, said,
+      ...(typeof rationale === 'string' && rationale.trim() ? { rationale: rationale.trim() } : {}),
+    });
+  };
+
+  for (const featureSet of Object.keys(declared ?? {}).sort()) {
+    const ontology = declared![featureSet]?.tagOntology as Ontology | undefined;
+    if (!ontology || typeof ontology !== 'object') continue;
+    ontologies[featureSet] = ontology;
+    const tags = ontology.tags && typeof ontology.tags === 'object' ? ontology.tags : {};
+    const ordered = Array.isArray(ontology.suggestedTreatment) ? ontology.suggestedTreatment
+      : Array.isArray(ontology.defaultTreatment) ? ontology.defaultTreatment : [];
+    for (const raw of ordered) {
+      if (!raw || typeof raw !== 'object') continue;
+      const r = raw as Record<string, unknown>;
+      const match = {
+        ...(tagList(r.tagsAny) ? { tagsAny: tagList(r.tagsAny) } : {}),
+        ...(tagList(r.tagsAll) ? { tagsAll: tagList(r.tagsAll) } : {}),
+        ...(tagList(r.tagsNone) ? { tagsNone: tagList(r.tagsNone) } : {}),
+      };
+      // A rule that names no tag would take every event the server sends: that is the agent's call to write, not an offer.
+      if (!match.tagsAny && !match.tagsAll) { untranslated.push({ featureSet, ...r }); continue; }
+      add(featureSet, match, r.behavior, r.rationale);
+    }
+    // Per-tag suggestions in tag order (UTF-8 bytes, as MCPL RFC-001 §5.2 and SPEC §16.5 order them):
+    // a JSON object's key order is no order at all.
+    const byTag = Object.keys(tags).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+    for (const tag of byTag) {
+      const descriptor = tags[tag];
+      const d = descriptor as Record<string, unknown> | null;
+      if (!d || typeof d !== 'object') continue;
+      if (typeof d.desc === 'string') tagDescriptions[tag] = d.desc;
+      if (d.suggestedTreatment !== undefined) add(featureSet, { tagsAny: [tag] }, d.suggestedTreatment, d.rationale);
+    }
+  }
+
+  if (rules.length === 0) {
+    rules.push({
+      n: 1, featureSet: '', match: { tagsAny: [...ATTENTION_TAGS] }, behavior: 'always', said: 'immediate', fallback: true,
+      rationale: 'This server suggests nothing the host can use. This rule wakes you for its events marked as addressed to you or waiting on you, and leaves the rest as they are.',
+    });
+  }
+  const named = new Set(rules.flatMap((r) => [...(r.match.tagsAny ?? []), ...(r.match.tagsAll ?? [])]));
+  for (const tag of Object.keys(tagDescriptions)) if (!named.has(tag)) delete tagDescriptions[tag];
+  const digest = Object.keys(ontologies).length > 0 ? stableHash({ server, ontologies }) : 'none';
+  return { server, digest, rules, tagDescriptions, untranslated };
+}
+
+export { ruleDecides } from './rule-scope.js';
+
+/**
+ * Whether the gate let an event go by without anyone having decided to: it did
+ * not wake and will not (`defer`/`skip`), by the default or by a rule that
+ * doesn't decide about it (ruleDecides). `policy` is the matched rule, as in
+ * force; undefined when the decision named none or it can't be found.
+ */
+export function isUndecided(decision: GateDecision, policy: GatePolicy | undefined): boolean {
+  if (decision.trigger) return false;
+  if (decision.behavior !== 'skip' && decision.behavior !== 'defer') return false;
+  if (decision.policyName === null) return true;
+  if (decision.policyName === 'asleep' || decision.policyName === 'gate.js') return false;
+  return policy !== undefined && !ruleDecides(policy);
+}
+
+export const carriesAttention = (tags: readonly string[] | undefined): boolean => (tags ?? []).some((t) => ATTENTION_TAGS.includes(t));
+
+/**
+ * Where an accepted rule goes: ahead of the first rule that would let the
+ * server's events by without deciding about them (a catch-all that defers or
+ * skips), so the rules the agent wrote for this server, or for a channel or
+ * tags, keep their place before it, and so do catch-alls that wake (a mention
+ * rule on metadata): a muted suggestion can't swallow an explicit mention.
+ * Null: there is none; the rule goes last, ahead of the default. (Accepted
+ * rules name their source, so they are never the catch-all.)
+ */
+export const placementFor = (policies: readonly GatePolicy[]): string | null => firstCatchAll(policies, { lettingBy: true });
+
+/** The gate rules accepting `rules` of `offer` writes. */
+export function rulesToWrite(offer: ServerOffer, accepted: readonly OfferedRule[]): GatePolicy[] {
+  return accepted.map((r) => ({
+    name: suggestedRuleName(offer.server, r.n),
+    match: { source: offer.server, ...r.match },
+    behavior: r.behavior,
+  }));
+}
+
+// ---------------------------------------------------------------- decisions
+
+/** The least time between two offers for one server (WakeDecisions.mayOffer). */
+export const OFFER_FLOOR_MS = 24 * 60 * 60 * 1000;
+
+export type DecisionState = 'offered' | 'accepted' | 'declined';
+export interface DecisionRecord {
+  digest: string;
+  state: DecisionState;
+  /** The rule names an acceptance wrote (kept while a newer ontology is being asked about). */
+  rules?: string[];
+  /** The digest whose numbered list the agent was last shown, when newer than `digest` (a drift refusal re-showed it). */
+  shown?: string;
+  at: string;
+}
+
+/**
+ * The agent's decisions per server, beside gate.json (`wake-decisions.json`).
+ * Written whole, through a temporary file; one that can't be read is set aside
+ * and starts empty, so a damaged file costs a repeated offer, never a crash.
+ */
+export class WakeDecisions {
+  private records: Record<string, DecisionRecord> = {};
+
+  constructor(private readonly path: string, private readonly log: (message: string) => void = () => undefined) {
+    if (!existsSync(path)) return;
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8')) as { servers?: Record<string, DecisionRecord> };
+      for (const [server, r] of Object.entries(parsed.servers ?? {})) {
+        if (r && typeof r.digest === 'string' && (r.state === 'offered' || r.state === 'accepted' || r.state === 'declined')) this.records[server] = r;
+      }
+    } catch (error) {
+      const aside = `${path}.unreadable-${Date.now()}`;
+      try { renameSync(path, aside); } catch { /* leave it */ }
+      this.log(`wake decisions: ${path} could not be read (${(error as Error).message}); set aside as ${aside}, starting empty`);
+    }
+  }
+
+  get(server: string): DecisionRecord | undefined { return this.records[server]; }
+
+  /**
+   * Whether an offer for `server` may go out now: never twice for the same
+   * digest, answered or not, and not within OFFER_FLOOR_MS of the server's
+   * last offer or decision even when its ontology changed — a server can't
+   * buy itself a stream of questions by editing what it declares.
+   */
+  /** Whether an offer for `server` could go out at all, before its digest is known: not within the floor of the last one. */
+  mayOfferSoon(server: string, now = Date.now()): boolean {
+    const r = this.records[server];
+    if (!r) return true;
+    const at = Date.parse(r.at);
+    return !Number.isFinite(at) || now - at >= OFFER_FLOOR_MS;
+  }
+
+  mayOffer(server: string, digest: string, now = Date.now()): boolean {
+    const r = this.records[server];
+    if (!r) return true;
+    if (r.digest === digest || r.shown === digest) return false;
+    const at = Date.parse(r.at);
+    return !Number.isFinite(at) || now - at >= OFFER_FLOOR_MS;
+  }
+
+  set(server: string, record: Omit<DecisionRecord, 'at'>, now = Date.now()): DecisionRecord {
+    const r: DecisionRecord = { ...record, at: new Date(now).toISOString() };
+    this.records[server] = r;
+    this.write();
+    return r;
+  }
+
+  /** Record that the agent was shown `digest`'s list, leaving the decision and its time as they are (the floor doesn't restart). */
+  markShown(server: string, digest: string): void {
+    const r = this.records[server];
+    if (!r) return;
+    this.records[server] = { ...r, shown: digest };
+    this.write();
+  }
+
+  all(): Readonly<Record<string, DecisionRecord>> { return this.records; }
+
+  private write() {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      const tmp = `${this.path}.tmp-${process.pid}`;
+      writeFileSync(tmp, JSON.stringify({ servers: this.records }, null, 2) + '\n');
+      renameSync(tmp, this.path);
+    } catch (error) {
+      this.log(`wake decisions: could not write ${this.path}: ${(error as Error).message}`);
+    }
+  }
+}

package/src/held-writes.ts

@@ -1,73 +1,62 @@
-import type { MessageId, MessageQuery, StoredMessage } from '@animalabs/context-manager';
+import { suppressionRecordOf } from './gate/suppression-stats.js';
+import type { ContextManager, MessageId, StoredMessage } from '@animalabs/context-manager';
 
 /**
- * The id a module holds for a write the framework holds. addMessage holds a
- * write while its agent's turn is alive or the host is quiesced, and stores
- * it at a later boundary. Until then, a module's context answers its id as a
- * handle: `held:` and the write's id in the deferred queue. The context's
- * getMessage, editMessage and removeMessage take the handle as they take a
- * stored id, as a process answer's edits and removals do, and once the write
- * lands, the handle names the stored row, which carries the write's id as
- * `metadata.deferredWriteId`.
+ * The id a release before #291 gave a module for a write it held while the
+ * write's agent's turn was alive: `held:` and the write's id in its deferred
+ * queue, which the stored row carries as `metadata.deferredWriteId` once it
+ * lands. This release stores every write at once and answers its stored id,
+ * unless a surgery's hold or a context manager refusing its work keeps the
+ * write in memory, where it answers '', so no write gets a handle any more.
+ * A module may have kept one across the upgrade: for one release the
+ * context's getMessage, editMessage and removeMessage still take it, and
+ * reach the row its write landed as (AgentFramework.landedRow), which the
+ * importer stores at boot for a write that release left queued.
  */
 const HELD = 'held:';
 
-export function heldHandle(writeId: string): MessageId {
-  return `${HELD}${writeId}`;
-}
-
-/** The deferred write a handle names, or undefined for any other id. A value
- *  that isn't a string, which only an untyped caller passes, is no handle,
- *  and goes on to the store as it did before handles. */
+/** The queued write a `held:` handle names, or undefined for any other id. A
+ *  value that isn't a string, which only an untyped caller passes, is no
+ *  handle, and goes on to the store as it did before handles. */
 export function heldWriteId(id: MessageId): string | undefined {
   return typeof id === 'string' && id.startsWith(HELD) ? id.slice(HELD.length) : undefined;
 }
 
-/**
- * Whether a row matches `filter` as context-manager's queryMessages matches a
- * stored one. That's its MessageStore's private matchesFilter, the same at
- * 0.14.1, 0.16.0, 0.17.1 and 0.18.0, which the package doesn't export, so the rule is copied
- * here, and a test compares the two on the same rows. A row matches the external source, one of the
- * external ids (an empty list filters nothing), the participant, and each
- * metadata path, dot-separated, by strict equality.
- */
-export function matchesMessageQuery(row: Pick<StoredMessage, 'participant' | 'metadata'>, filter: MessageQuery): boolean {
-  const external = row.metadata?.external as { source?: unknown; id?: unknown } | undefined;
-  if (filter.source !== undefined && external?.source !== filter.source) return false;
-  if (
-    filter.externalIds !== undefined &&
-    filter.externalIds.length > 0 &&
-    (!external?.id || !filter.externalIds.includes(external.id as string))
-  ) {
-    return false;
-  }
-  if (filter.participant !== undefined && row.participant !== filter.participant) return false;
-  if (filter.metadata !== undefined) {
-    for (const [path, value] of Object.entries(filter.metadata)) {
-      if (valueAt(row.metadata, path) !== value) return false;
-    }
-  }
-  return true;
-}
-
-function valueAt(value: unknown, path: string): unknown {
-  for (const part of path.split('.')) {
-    if (value === undefined || value === null || typeof value !== 'object') return undefined;
-    value = (value as Record<string, unknown>)[part];
-  }
-  return value;
-}
+/** What asModuleRow reads of the window of the agent a read is for. */
+export type ModuleRowWindow = Pick<ContextManager, 'windowMode' | 'ordinalOf'>;
 
 /**
- * A row as a module's context answers it: marked `heldFromResidents` when it
- * carries the stamp a tune-out puts on a message it holds from the residents
- * (`metadata.tuneOut`). Every resident's viewFilter leaves a stamped row out
- * of its compiled view (framework.ts, createAgent), and a resident's tool
- * boundary stores a stamped write without injecting it into the live turn, so
- * a marked row is one the store keeps and no resident is shown
- * (ModuleMessage.heldFromResidents says where its text can still reach
- * one). Any other row comes back as it is.
+ * A row as a module's context answers it, for the agent whose store it was
+ * read from:
+ *
+ * - `heldFromResidents` when it carries the stamp a tune-out puts on a
+ *   message it holds from the residents (`metadata.tuneOut`). Every
+ *   resident's viewFilter leaves a stamped row out of its compiled view
+ *   (framework.ts, createAgent), and a tool boundary never presents one to a
+ *   resident, so a marked row is one the store keeps and no resident is
+ *   shown (ModuleMessage.heldFromResidents says where its text can still
+ *   reach one). So is a row a suppress rule hid (`metadata.suppressed`),
+ *   which no view shows either, nor any window presents (one stored before
+ *   audience stamps stays in a window written down from the record; the
+ *   view still leaves it out).
+ * - `held` when that agent's window (`window`) presents rows and doesn't
+ *   hold it (#291): stored and not yet presented to the agent, which its
+ *   next presentation point does, or taken out of it as an undone turn's,
+ *   or one it is never presented, as a held row is for a resident. Never in
+ *   legacy mode, where the window is the record. A resident's window
+ *   written down from the record holds the held rows an earlier release
+ *   stored, unstamped, so those read without `held`: `heldFromResidents`
+ *   marks every held row.
+ *
+ * Any other row comes back as it is.
  */
-export function asModuleRow<T extends Pick<StoredMessage, 'metadata'>>(row: T): T & { heldFromResidents?: true } {
-  return (row.metadata as { tuneOut?: unknown } | undefined)?.tuneOut ? { ...row, heldFromResidents: true } : row;
+export function asModuleRow<T extends Pick<StoredMessage, 'id' | 'metadata'>>(
+  row: T,
+  window?: ModuleRowWindow,
+): T & { heldFromResidents?: true; held?: true } {
+  const metadata = row.metadata as Record<string, unknown> | undefined;
+  const fromResidents = !!metadata?.tuneOut || suppressionRecordOf(metadata) !== undefined;
+  const held = window !== undefined && window.windowMode() === 'presented' && window.ordinalOf(row.id) === undefined;
+  if (!fromResidents && !held) return row;
+  return { ...row, ...(fromResidents ? { heldFromResidents: true as const } : {}), ...(held ? { held: true as const } : {}) };
 }

package/src/index.ts

@@ -8,6 +8,13 @@ export { Agent } from './agent.js';
 export { FLAT_MINIMUM_MS, type InferenceBoundsOptions } from './inference-bounds.js';
 export { storedInjectionMarkOf, type StoredInjectionMark } from './stored-injections.js';
 export type { StartStreamResult } from './agent.js';
+export type { PresentationOccasion } from './presentation.js';
+export { covers, coverTest, describeReadMark, markAtOrAfter, type Cover, type MarkCm, type MarkedRow, type ReadMark } from './read-marks.js';
+// How a resident's context and the subconscious's are opened (#291), for a host that opens one itself.
+export {
+  residentContextOptions, residentViewFilter, subconsciousContextOptions, subconsciousViewFilter,
+  type ContextManagerOpenOptions,
+} from './context-options.js';
 export { ProcessQueueImpl } from './queue.js';
 export { ModuleRegistry } from './module-registry.js';
 export { ShutdownTimeoutError, DEFAULT_SHUTDOWN_TIMEOUT_MS } from './shutdown.js';
@@ -73,9 +80,9 @@ export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent
 
 // EventGate
 export { EventGate, MCPL_GATE_EVENT_TYPES, wakeLineText, type EventTypesFrom, type WakeProvenance, type WritePlacement } from './gate/index.js';
-export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior, WakeLine } from './gate/index.js';
+export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior, WakeLine, SuppressConfig, SuppressionReviewOptions } from './gate/index.js';
 export { ReplyJudge, DEFAULT_JUDGE_MODEL, DEFAULT_JUDGE_MAX_INPUT_TOKENS, MIN_JUDGE_INPUT_TOKENS } from './gate/index.js';
-export type { JudgeConfig, JudgeEventSummary, JudgeFn, JudgeRequest, JudgeVerdict, ReplyJudgeOptions, ReplyJudgeDeps, UpcomingWake } from './gate/index.js';
+export type { JudgeConfig, JudgeEventSummary, JudgeFn, JudgeRequest, JudgeVerdict, ReplyJudgeOptions, ReplyJudgeDeps, UpcomingWake, UpcomingWakeKind } from './gate/index.js';
 export { Heartbeat, DEFAULT_HEARTBEAT, HEARTBEAT_TOOL_PREFIX } from './heartbeat/heartbeat.js';
 export type { HeartbeatOptions, HeartbeatSettings, HeartbeatWake, HeartbeatDeliveryMode, HeartbeatScheduledWake, Reminder } from './heartbeat/heartbeat.js';
 

package/src/jsonrpc-envelope.ts

@@ -0,0 +1,81 @@
+/**
+ * A JSON-RPC 2.0 message's envelope, read once where a message arrives, by
+ * each of the framework's endpoints that answers requests: the MCPL
+ * connection, for its servers' requests, and the MCP server
+ * (src/api/mcp-server-core.ts), for its client's.
+ *
+ * A message with an id member and no method is a response, whatever the
+ * id's value: a peer answers a request it couldn't read with id null (§5),
+ * and taking that answer for a request would answer it in turn. So is an
+ * error with no id, which MCP lets a peer send for a request it couldn't
+ * read (MCP 2025-11-25, Basic, Error Responses), but only from a message
+ * whose jsonrpc member is "2.0": a peer's own JSON log lines, which an MCPL
+ * server's stdout can carry, can have an error key. Any other object with
+ * neither a method nor an id isn't JSON-RPC: the MCP server answers it
+ * -32600 with id null, as it does a value that isn't an object, and the MCPL
+ * connection, whose server's stdout carries other output, ignores it. A
+ * message with a method is a request when it has an id member, whatever its
+ * value, and a notification when it has none (§4.1), so `"id": null` is a
+ * request. MCP says a request's id MUST NOT be null (2025-11-25, Basic); one
+ * is served anyway, as JSON-RPC allows, since its sender waits for the
+ * answer. A request's method must be a string and its id a string, a number
+ * or null (§4). A message that breaks either isn't a Request object, and so
+ * isn't a notification either, with or without an id: the endpoints answer
+ * it once with -32600, carrying its id where that's a string or a number and
+ * null otherwise (§5, and the spec's own example of an invalid Request
+ * object, which has no id), and don't dispatch it. The MCPL handshake, which
+ * answers only pings, ignores it, as it ignores every other request then.
+ * Apart from the error with no id, the `jsonrpc` member isn't checked: a
+ * peer that leaves it out is served, as before.
+ */
+
+/** A JSON value's kind, as a log line or an error names what a peer sent
+ *  without repeating it: "null", "an array", "an object", "a number". */
+export function jsonKind(value: unknown): string {
+  if (value === null) return 'null';
+  const kind = Array.isArray(value) ? 'array' : typeof value;
+  return `${/^[aeiou]/.test(kind) ? 'an' : 'a'} ${kind}`;
+}
+
+export type JsonRpcEnvelope =
+  /** An id member and no method, or a JSON-RPC 2.0 error with neither: an
+   *  answer, which the endpoint matches to one of its own requests by the
+   *  id where it can. */
+  | { kind: 'response' }
+  /** Neither a method nor an id member, and not such an error: not a
+   *  JSON-RPC message. */
+  | { kind: 'neither' }
+  | { kind: 'request'; method: string; id: string | number | null }
+  | { kind: 'notification'; method: string }
+  /** Not a Request object, with or without an id: answered with `error`,
+   *  carrying `id`, and not dispatched. `method` is its method where that's
+   *  a string, for a log line. */
+  | { kind: 'invalid'; id: string | number | null; error: { code: -32600; message: string }; method?: string; problems: string };
+
+/** Read a parsed message's envelope. What to do with a value that isn't an
+ *  object is the endpoint's own call. */
+export function readEnvelope(msg: Record<string, unknown>): JsonRpcEnvelope {
+  if (!Object.hasOwn(msg, 'method')) {
+    const answers = Object.hasOwn(msg, 'id') || (msg.jsonrpc === '2.0' && Object.hasOwn(msg, 'error'));
+    return { kind: answers ? 'response' : 'neither' };
+  }
+  const isRequest = Object.hasOwn(msg, 'id');
+  const { method, id } = msg;
+  const problems = [
+    ...(typeof method === 'string' ? [] : [`the method must be a string, not ${jsonKind(method)}`]),
+    ...(!isRequest || typeof id === 'string' || typeof id === 'number' || id === null
+      ? [] : [`the id must be a string, a number or null, not ${jsonKind(id)}`]),
+  ].join('; ');
+  if (problems) {
+    return {
+      kind: 'invalid',
+      id: typeof id === 'string' || typeof id === 'number' ? id : null,
+      error: { code: -32600, message: `Invalid Request: ${problems}` },
+      ...(typeof method === 'string' ? { method } : {}),
+      problems,
+    };
+  }
+  return isRequest
+    ? { kind: 'request', method: method as string, id: id as string | number | null }
+    : { kind: 'notification', method: method as string };
+}