@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-node/src/services/injector.ts

@@ -0,0 +1,135 @@
+/**
+ * Service Documentation
+ * Service ID: injector
+ * Service Name: Injector
+ * Runtime: hkp-node
+ * Modes: none
+ * Key Config: inject, injectBinary, recentInjection, plainText
+ * IO: in=any -> out=stored injection (or identity when nothing was injected)
+ * Arrays: pass-through
+ * Binary: supported (base64 via injectBinary, decoded to a Buffer)
+ * MixedData: pass-through only
+ */
+import {
+  HostedService,
+  JsonRecord,
+  RuntimeHost,
+  RuntimeNotification,
+  ServiceConfiguration,
+  ServiceRegistryEntry,
+} from "../types";
+
+export const injectorDescriptor: ServiceRegistryEntry = {
+  serviceId: "injector",
+  serviceName: "Injector",
+};
+
+export class InjectorService implements HostedService {
+  readonly serviceId = injectorDescriptor.serviceId;
+  readonly serviceName = injectorDescriptor.serviceName;
+  readonly uuid: string;
+
+  private host: RuntimeHost | null = null;
+  private injection: unknown = undefined;
+  private hasInjection = false;
+  private plainText = false;
+
+  constructor(config: ServiceConfiguration) {
+    this.uuid = config.uuid;
+    if (config.state) {
+      this.configure(config.state);
+    }
+  }
+
+  setHost(host: RuntimeHost): void {
+    this.host = host;
+  }
+
+  getState(): JsonRecord {
+    return this.injectionState();
+  }
+
+  configure(config: JsonRecord): JsonRecord {
+    if (config.inject !== undefined) {
+      this.setInjection(config.inject);
+      this.emitInjection();
+    }
+
+    if (typeof config.injectBinary === "string") {
+      this.setInjection(Buffer.from(config.injectBinary, "base64"));
+      this.emitInjection();
+    }
+
+    // Restores what was injected (e.g. from persisted board state) without
+    // re-triggering the pipeline the way inject/injectBinary do.
+    if (config.recentInjection !== undefined) {
+      this.setInjection(config.recentInjection);
+    }
+
+    if (typeof config.plainText === "boolean") {
+      this.plainText = config.plainText;
+      this._notify({ plainText: this.plainText });
+    }
+
+    return this.getState();
+  }
+
+  process(
+    input: unknown,
+    _notify: (payload: unknown, instanceId?: string) => void,
+  ): unknown {
+    return this.hasInjection ? this.injection : input;
+  }
+
+  destroy(): void {
+    this.host = null;
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────
+
+  private setInjection(value: unknown): void {
+    this.injection = value;
+    this.hasInjection = true;
+    this._notify(this.injectionState());
+  }
+
+  /**
+   * Runs the services after Injector with the value just set. inject and
+   * injectBinary act immediately rather than waiting for the next call to
+   * reach this service, mirroring the browser (`app.next`) and hkp-rt
+   * (`emit`) implementations.
+   */
+  private emitInjection(): void {
+    const host = this.host;
+    if (!host) {
+      return;
+    }
+    // No-op notification callback: processFrom already fans notifications out
+    // to the runtime's own notification targets, so re-notifying through the
+    // host here would deliver every one twice.
+    void host
+      .processFrom(this.uuid, this.injection, (_n: RuntimeNotification) => {})
+      .then((result) => host.emitResult(result));
+  }
+
+  /**
+   * The stored injection as it is reported to the frontend. A binary payload
+   * is described by its size instead of being echoed back.
+   */
+  private injectionState(): JsonRecord {
+    const state: JsonRecord = { plainText: this.plainText };
+    if (!this.hasInjection) {
+      return state;
+    }
+    if (this.injection instanceof Uint8Array) {
+      state.recentInjectionSize = this.injection.length;
+    } else {
+      state.recentInjection = this.injection;
+    }
+    return state;
+  }
+
+  private _notify(payload: JsonRecord, instanceId: string = this.uuid): void {
+    this.host?.notify(payload, instanceId);
+  }
+}

package/bundle/hkp-node/src/services/iterator.ts

@@ -0,0 +1,203 @@
+/**
+ * Service Documentation
+ * Service ID: iterator
+ * Service Name: Iterator
+ * Runtime: hkp-node
+ * Modes: one pass of the nested pipeline per item
+ * Key Config: itemsFrom, limit, pipeline, bypass
+ * IO: in=an array, or a single item -> out=the results, or nothing at all
+ * Arrays: the point of the service
+ * Binary: passed to the nested pipeline untouched
+ * MixedData: not native in runtime
+ *
+ * Iteration as a service, so a board can express it without a service having to
+ * grow its own loop.
+ *
+ * A pipeline pass carries one value, which is a problem for anything that
+ * produces several: a poll finds four conversations, a query returns twenty
+ * rows. The alternatives are both bad — hand the whole array to the next
+ * service and make it, and everything after it, loop internally; or let the
+ * service that found them call the rest of the pipeline itself, which buries
+ * the iteration in whichever service happened to need it first. Iterator is the
+ * third option, and the composable one: the thing that produced the array says
+ * only what it found, and iteration is a service you can see in the board.
+ *
+ * **A single item is an array of one.** A board that grows from "the one that
+ * arrived" to "the four that were waiting" does not change shape, and neither
+ * does an Iterator fed by something that sometimes returns one row.
+ *
+ * What the nested pipeline returns for an item is collected, and an item whose
+ * pipeline **stopped** contributes nothing — so a `filter`-shaped sub-pipeline
+ * makes this a filter, using the same `null` that stops a pipeline everywhere
+ * else. Nothing collected at all means nothing to pass on, and the outer
+ * pipeline stops here rather than continuing with an empty array.
+ *
+ * Items are taken one at a time, each awaited before the next begins. A pass
+ * that calls a model is then one request in flight rather than ten at once,
+ * which is what an inference provider's rate limit wants; the cost is that a
+ * poll takes as long as its items put together.
+ *
+ * **One item failing does not end the loop.** Nine conversations should not go
+ * unprocessed because the tenth had a malformed address. Failures are counted
+ * and reported rather than thrown.
+ */
+import {
+  JsonRecord,
+  ServiceConfiguration,
+  ServiceCreator,
+  ServiceRegistryEntry,
+} from "../types";
+import { childRun } from "../runtime";
+import { SubService } from "./sub-service";
+
+export const iteratorDescriptor: ServiceRegistryEntry = {
+  serviceId: "iterator",
+  serviceName: "Iterator",
+  version: "v1",
+  // Same as SubService: this service holds a pipeline, and the board's UI needs
+  // to know that to let anyone look inside it.
+  capabilities: ["subservices"],
+};
+
+/** The value at a dotted path, or undefined where the path does not lead. */
+function valueAt(input: unknown, path: string): unknown {
+  if (!path) {
+    return undefined;
+  }
+  let current: unknown = input;
+  for (const step of path.split(".")) {
+    if (current === null || typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as JsonRecord)[step];
+  }
+  return current;
+}
+
+export class IteratorService extends SubService {
+  readonly serviceId = iteratorDescriptor.serviceId;
+  readonly serviceName = iteratorDescriptor.serviceName;
+  readonly version = iteratorDescriptor.version;
+  readonly capabilities = iteratorDescriptor.capabilities;
+
+  private itemsFrom = "";
+  private limit = 0;
+  private lastItems = 0;
+  private lastFailed = 0;
+
+  constructor(config: ServiceConfiguration, createService: ServiceCreator) {
+    super(config, createService);
+    // Again, and not redundantly.
+    //
+    // The base constructor calls `configure`, which dispatches to the override
+    // below — but a subclass's fields are defined only once `super()` has
+    // returned, so everything it read was then overwritten by the declarations
+    // above. (Declaring them without an initialiser does not help: a class
+    // field is defined as `undefined` either way.) Re-reading here is what
+    // makes an Iterator configured in the board behave like one configured later.
+    // `settle` touches nothing the base owns, so the pipeline is not rebuilt.
+    if (config.state) {
+      this.settle(config.state);
+    }
+  }
+
+  configure(config: JsonRecord): JsonRecord {
+    this.settle(config);
+    // The pipeline, bypass and the editing commands belong to the base.
+    super.configure(config);
+    return this.getState();
+  }
+
+  getState(): JsonRecord {
+    return {
+      ...super.getState(),
+      itemsFrom: this.itemsFrom,
+      limit: this.limit,
+      lastItems: this.lastItems,
+      lastFailed: this.lastFailed,
+    };
+  }
+
+  /** The part of a configuration this service owns rather than its base. */
+  private settle(config: JsonRecord): void {
+    if (typeof config.itemsFrom === "string") {
+      this.itemsFrom = config.itemsFrom;
+    }
+    if (typeof config.limit === "number" && config.limit >= 0) {
+      this.limit = Math.floor(config.limit);
+    }
+  }
+
+  async process(
+    input: unknown,
+    notify: (payload: unknown, instanceId?: string) => void,
+  ): Promise<unknown> {
+    if (
+      this.bypass ||
+      !this.pipeline ||
+      this.pipeline.listServices().length === 0
+    ) {
+      // Nothing to run the items through. Passing the input on unchanged is
+      // what an empty SubService does, and keeps a half-built board legible —
+      // unless this one passes nothing on at all, which it says whether or not
+      // there was anything to run.
+      return this.stopPropagation ? null : input;
+    }
+
+    const items = this.items(input);
+    const parent = this.host?.currentContext() ?? null;
+    const results: unknown[] = [];
+    let failed = 0;
+
+    for (const item of items) {
+      try {
+        // A run of its own per item, descended from the run that reached the
+        // Iterator. That is what makes a log answer "what happened to this one"
+        // rather than only "what happened on this tick".
+        const result = await this.pipeline.process(
+          item,
+          () => {},
+          childRun(parent),
+        );
+        if (result !== null && result !== undefined) {
+          results.push(result);
+        }
+      } catch (error) {
+        failed += 1;
+        this.host?.log("error", "service.failed", {
+          message: `iterator item failed: ${reason(error)}`,
+        });
+      }
+    }
+
+    this.lastItems = items.length;
+    this.lastFailed = failed;
+    notify({ items: items.length, results: results.length, failed });
+
+    if (this.stopPropagation) {
+      return null;
+    }
+    return results.length > 0 ? results : null;
+  }
+
+  /**
+   * What to iterate over.
+   *
+   * `itemsFrom` is how an Iterator reaches into a result that says more than the
+   * list itself — `{ conversations, count }` rather than a bare array — so the
+   * service that produced it does not have to flatten its answer for the
+   * benefit of whatever comes next.
+   */
+  private items(input: unknown): unknown[] {
+    const source = this.itemsFrom ? valueAt(input, this.itemsFrom) : input;
+    if (source === null || source === undefined) {
+      return [];
+    }
+    const list = Array.isArray(source) ? source : [source];
+    return this.limit > 0 ? list.slice(0, this.limit) : list;
+  }
+}
+
+function reason(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/bundle/hkp-node/src/services/join.ts

@@ -0,0 +1,226 @@
+/**
+ * Service Documentation
+ * Service ID: join
+ * Service Name: Join
+ * Runtime: hkp-node
+ * Modes: overwrite | add
+ * Key Config: as, mode, onFailure (stop | merge), pipeline, bypass
+ * IO: in=any -> out=the input and the nested pipeline's result, together
+ * Arrays: the input is one value; nesting an `iterator` handles arrays
+ * Binary: passed to the nested pipeline untouched
+ * MixedData: not native in runtime
+ *
+ * Splitting off a piece of work and getting the answer back **beside** what you
+ * already had, rather than instead of it.
+ *
+ * Most services replace their input: `text-generation` answers with an answer,
+ * not with the question and the answer. That is right for the service and wrong
+ * for the pipeline around it, because whatever the input was carrying — which
+ * conversation this is, which record it came from — is gone by the time the
+ * answer arrives, and the service that has to file the answer no longer knows
+ * where it belongs.
+ *
+ * The usual workarounds are all bad: teach every service to pass its input
+ * through, which makes every output a pile of everything that ever touched it;
+ * ask a model to echo an id back, which makes correctness a matter of the model
+ * being careful; or keep the id somewhere on the side, which stops working the
+ * moment two runs overlap. Join is the structural answer — the carrier never
+ * goes anywhere, because the nested pipeline is a detour rather than the road.
+ *
+ *     input ──┬──────────────────────────────► merged output
+ *             └── nested pipeline ── result ──┘
+ *
+ * **`as` is the safe way to use it.** Naming a key puts the result there, and
+ * nothing the nested pipeline produces can collide with what the input was
+ * carrying. Merging at the top level is available for the cases where the two
+ * shapes are known to be disjoint.
+ *
+ * A nested pipeline that **stops** — returns `null` — stops this one too. The
+ * merge is the reason the Join is there, so continuing without it would hand
+ * the services downstream an input that looks like a successful merge and is
+ * not: a board that files the result would file nothing, under a name that says
+ * it filed something.
+ *
+ * **Unless it stopped because something in it failed, and the board asked to
+ * hear about it** (`onFailure: "merge"`). A detour can end with nothing for two
+ * reasons: a service chose to stop — a filter, a claim that found nothing to
+ * take — or a service failed, and said why in an `error` notification. The
+ * first is flow and still stops. The second, with `merge`, passes the input on
+ * with `{ error, service }` where the result would have gone — under `as`, or
+ * under `failure` when no name is given — so the services after the Join can
+ * record the failure beside the thing it happened to rather
+ * than the run ending with the reason in a notification nobody kept. Only a
+ * service directly in the detour is heard: one inside a scope of its own
+ * reports to that scope.
+ *
+ * A detour that takes its time is still a detour: the runtime awaits every
+ * service, so a nested `text-generation` taking a minute is waited for and its
+ * answer merged like any other. That is the whole reason the pipeline awaits —
+ * without it a service answering late has to call the rest of the pipeline
+ * itself, and there is no longer an input for anything to be re-joined with.
+ */
+import {
+  JsonRecord,
+  ServiceConfiguration,
+  ServiceCreator,
+  ServiceRegistryEntry,
+} from "../types";
+import { childRun } from "../runtime";
+import { SubService } from "./sub-service";
+
+export const joinDescriptor: ServiceRegistryEntry = {
+  serviceId: "join",
+  serviceName: "Join",
+  version: "v1",
+  // Holds a pipeline, so the board's UI must let anyone look inside it.
+  capabilities: ["subservices"],
+};
+
+type JoinMode = "overwrite" | "add";
+
+const MODES: JoinMode[] = ["overwrite", "add"];
+
+/** What a detour that failed does to this pipeline. */
+type FailureMode = "stop" | "merge";
+
+const FAILURE_MODES: FailureMode[] = ["stop", "merge"];
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export class JoinService extends SubService {
+  readonly serviceId = joinDescriptor.serviceId;
+  readonly serviceName = joinDescriptor.serviceName;
+  readonly version = joinDescriptor.version;
+  readonly capabilities = joinDescriptor.capabilities;
+
+  private as = "";
+  private mode: JoinMode = "overwrite";
+  private onFailure: FailureMode = "stop";
+
+  constructor(config: ServiceConfiguration, createService: ServiceCreator) {
+    super(config, createService);
+    // The base constructor already called `configure`, but a subclass's fields
+    // are defined only once `super()` returns — so what it read was overwritten
+    // by the declarations above. Reading it again is what makes a Join
+    // configured in the board behave like one configured later. See `iterator`,
+    // which has the same shape and the same note.
+    if (config.state) {
+      this.settle(config.state);
+    }
+  }
+
+  configure(config: JsonRecord): JsonRecord {
+    this.settle(config);
+    // The pipeline, bypass and the editing commands belong to the base.
+    super.configure(config);
+    return this.getState();
+  }
+
+  getState(): JsonRecord {
+    return {
+      ...super.getState(),
+      as: this.as,
+      mode: this.mode,
+      onFailure: this.onFailure,
+    };
+  }
+
+  async process(
+    input: unknown,
+    _notify: (payload: unknown, instanceId?: string) => void,
+  ): Promise<unknown> {
+    if (
+      this.bypass ||
+      !this.pipeline ||
+      this.pipeline.listServices().length === 0
+    ) {
+      return input;
+    }
+
+    // What this call's detour reported, and only this call's: the callback is
+    // handed to this one run of the pipeline, so two articles in flight at once
+    // never hear each other's failures.
+    let failure: { error: string; service: string } | null = null;
+    const result = await this.pipeline.process(
+      input,
+      (notification) => {
+        const error = isRecord(notification.payload)
+          ? notification.payload.error
+          : undefined;
+        if (typeof error !== "string") {
+          return;
+        }
+        if (error) {
+          failure = { error, service: notification.instanceId };
+        } else if (failure?.service === notification.instanceId) {
+          // A service clearing what it said before: it recovered.
+          failure = null;
+        }
+      },
+      childRun(this.host?.currentContext() ?? null),
+    );
+
+    if (result === null || result === undefined) {
+      if (failure && this.onFailure === "merge") {
+        return this.failed(input, failure);
+      }
+      // Nothing to merge, so nothing to pass on. Continuing with the input
+      // alone would be indistinguishable downstream from a merge that worked.
+      return null;
+    }
+
+    return this.merged(input, result);
+  }
+
+  /**
+   * The input with the detour's failure beside it, always under a name of its
+   * own: spread into the input like a result, an `error` the input already
+   * carried would hide it in `add` mode, and in `overwrite` it would replace
+   * the input's own `service`.
+   */
+  private failed(
+    input: unknown,
+    failure: { error: string; service: string },
+  ): unknown {
+    const as = this.as || "failure";
+    return isRecord(input) ? { ...input, [as]: failure } : { input, [as]: failure };
+  }
+
+  /** The input with what came back from the detour beside it. */
+  private merged(input: unknown, result: unknown): unknown {
+    if (this.as) {
+      return isRecord(input)
+        ? { ...input, [this.as]: result }
+        : { input, [this.as]: result };
+    }
+
+    if (!isRecord(input) || !isRecord(result)) {
+      // Nothing to merge into or nothing to merge: a scalar or an array on
+      // either side has no fields to combine, and silently dropping one of them
+      // would be worse than saying which one a board gets.
+      return isRecord(result) ? result : input;
+    }
+
+    return this.mode === "add"
+      ? { ...result, ...input }
+      : { ...input, ...result };
+  }
+
+  /** The part of a configuration this service owns rather than its base. */
+  private settle(config: JsonRecord): void {
+    if (typeof config.as === "string") {
+      this.as = config.as;
+    }
+    if (typeof config.mode === "string" && MODES.includes(config.mode as JoinMode)) {
+      this.mode = config.mode as JoinMode;
+    }
+    if (
+      typeof config.onFailure === "string" &&
+      FAILURE_MODES.includes(config.onFailure as FailureMode)
+    ) {
+      this.onFailure = config.onFailure as FailureMode;
+    }
+  }
+}