@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-frontend/src/runtime/browser/services/workflow-prompt/RefinementSession.ts

@@ -0,0 +1,121 @@
+import { BoardDescriptor } from "hkp-frontend/src/types";
+
+export const WORKFLOW_REFINEMENT_SEED_KEY = "hkp-ai-workflow-refinement-seed";
+export const WORKFLOW_REFINER_TEMPLATE_BOARD_NAME = "AI-Board-Refiner";
+
+export type WorkflowRefinementSeed = {
+  sourceBoardName: string;
+  baseBoardSource: string;
+  createdAt: string;
+  initialPrompt?: string;
+};
+
+export function saveWorkflowRefinementSeed(seed: WorkflowRefinementSeed) {
+  localStorage.setItem(WORKFLOW_REFINEMENT_SEED_KEY, JSON.stringify(seed));
+}
+
+export function consumeWorkflowRefinementSeed(): WorkflowRefinementSeed | null {
+  const raw = localStorage.getItem(WORKFLOW_REFINEMENT_SEED_KEY);
+  if (!raw) {
+    return null;
+  }
+
+  localStorage.removeItem(WORKFLOW_REFINEMENT_SEED_KEY);
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed.sourceBoardName === "string" &&
+      typeof parsed.baseBoardSource === "string"
+    ) {
+      return {
+        sourceBoardName: parsed.sourceBoardName,
+        baseBoardSource: parsed.baseBoardSource,
+        createdAt:
+          typeof parsed.createdAt === "string"
+            ? parsed.createdAt
+            : new Date().toISOString(),
+        initialPrompt:
+          typeof parsed.initialPrompt === "string"
+            ? parsed.initialPrompt
+            : undefined,
+      };
+    }
+  } catch (_err) {
+    return null;
+  }
+
+  return null;
+}
+
+export function createWorkflowRefinerTemplateBoard(): BoardDescriptor & {
+  description: string;
+} {
+  const runtimeId = "rt-browser-refiner";
+  const seed = consumeWorkflowRefinementSeed();
+
+  let initialBoardPayload: any = {};
+  if (seed?.baseBoardSource?.trim()) {
+    try {
+      initialBoardPayload = JSON.parse(seed.baseBoardSource);
+    } catch (_err) {
+      initialBoardPayload = {
+        rawBoardSource: seed.baseBoardSource,
+      };
+    }
+  }
+
+  const wrappedBoardPayload = {
+    boardSource: initialBoardPayload,
+  };
+
+  return {
+    boardName: WORKFLOW_REFINER_TEMPLATE_BOARD_NAME,
+    description:
+      "AI refinement template: Injector emits current board JSON once, Workflow Builder refines, then push output to Board-Service preview.",
+    runtimes: [
+      {
+        id: runtimeId,
+        name: "Browser Runtime",
+        type: "browser",
+        state: {
+          wrapServices: false,
+          minimized: false,
+        },
+      },
+    ],
+    services: {
+      [runtimeId]: [
+        {
+          uuid: "svc-injector-base-board",
+          serviceId: "hookup.to/service/injector",
+          serviceName: "Injector",
+          state: {
+            recentInjection: JSON.stringify(wrappedBoardPayload, null, 2),
+            plainText: false,
+          },
+        },
+        {
+          uuid: "svc-workflow-board-builder-refiner",
+          serviceId: "hookup.to/service/workflow-board-builder",
+          serviceName: "Workflow Board Builder",
+          state: {
+            description:
+              seed?.initialPrompt ||
+              "Refine the current board while preserving unchanged behavior.",
+            generatedBoardSource: "",
+            isEditorOpen: false,
+          },
+        },
+        {
+          uuid: "svc-board-service-preview",
+          serviceId: "hookup.to/service/board-service",
+          serviceName: "Board-Service",
+          state: {},
+        },
+      ],
+    },
+    registry: {},
+  };
+}

package/bundle/hkp-frontend/src/runtime/browser/services/workflow-prompt/SystemPromptCatalog.ts

@@ -0,0 +1,245 @@
+import { AppInstance } from "hkp-frontend/src/types";
+
+type ServicePromptSpec = {
+  modes?: string;
+  config?: string;
+  input?: string;
+  output?: string;
+  arrays?: string;
+  binary?: string;
+  mixedData?: string;
+};
+
+const DEFAULT_SPEC: Required<ServicePromptSpec> = {
+  modes: "unspecified",
+  config: "unspecified",
+  input: "any/unknown",
+  output: "unknown",
+  arrays: "unknown",
+  binary: "unknown",
+  mixedData:
+    "not native (assume false unless runtime-specific note says otherwise)",
+};
+
+const HKP_PYTHON_SERVICES = [
+  "monitor",
+  "map",
+  "sub-service",
+  "http-server-subservices",
+  "timer",
+];
+
+const HKP_NODE_SERVICES = ["hookup.to/service/monitor"];
+
+const HKP_RT_SERVICES = [
+  "buffer",
+  "cache",
+  "cache-subservices",
+  "core-input",
+  "core-output",
+  "fft",
+  "filesystem",
+  "ffmpeg",
+  "filter",
+  "http-client",
+  "http-server",
+  "http-server-subservices",
+  "ifft",
+  "map",
+  "monitor",
+  "mp4-to-wav",
+  "static",
+  "sub-service",
+  "timer",
+  "transients",
+  "wav-reader",
+  "websocket-client",
+  "websocket-reader",
+  "websocket-socket",
+  "websocket-writer",
+];
+
+const BROWSER_SERVICE_SPECS: Record<string, ServicePromptSpec> = {
+  "hookup.to/service/timer": {
+    modes: "periodic|oneShot",
+    config:
+      "periodic,periodicValue,periodicUnit,oneShotDelay,oneShotDelayUnit,running,start,stop,restart,immediate,until.triggerCount",
+    input: "any for oneShot delay path",
+    output: "{triggerCount,...input?} on tick or delayed pass-through",
+    arrays: "treats array as generic input",
+    binary: "pass-through in delayed mode",
+    mixedData: "not native",
+  },
+  "hookup.to/service/map": {
+    modes: "replace|add|overwrite plus sensingMode",
+    config: "template (keys ending '=' are expressions),mode,sensingMode",
+    input: "object|array|scalar",
+    output: "mapped object/scalar; null when sensingMode captures template",
+    arrays: "maps each element",
+    binary: "not intended for raw binary",
+    mixedData: "not native",
+  },
+  "hookup.to/service/filter": {
+    modes: "aggregator and|or",
+    config: "conditions:string|string[],aggregator",
+    input: "object|array",
+    output: "input if predicate true; null if false",
+    arrays: "filters array entries",
+    binary: "not intended",
+    mixedData: "not native",
+  },
+  "hookup.to/service/buffer": {
+    modes: "capacity flush and/or interval flush",
+    config: "capacity,interval(sec),accumulatedOutput,action=clear",
+    input: "any",
+    output:
+      "slice array on capacity flush; whole buffered array on timer flush; or null",
+    arrays: "concats input arrays into buffer",
+    binary: "can carry binary as opaque values",
+    mixedData: "not native",
+  },
+  "hookup.to/service/canvas": {
+    modes: "render pass-through or capture",
+    config: "size,resizable,clearOnRedraw,fullscreen,capture,reportSizeUpdate",
+    input: "draw payload object/array",
+    output:
+      "same payload by default; Blob frame when capture enabled; size updates via next",
+    arrays: "passed through",
+    binary: "outputs Blob in capture mode",
+    mixedData: "not native",
+  },
+  "hookup.to/service/monitor": {
+    modes: "observe",
+    config: "logToConsole",
+    input: "any",
+    output: "identity pass-through",
+    arrays: "pass-through",
+    binary: "UI can inspect Blob/ArrayBuffer/Uint8Array",
+    mixedData: "not native",
+  },
+  "hookup.to/service/select": {
+    modes: "index select",
+    config: "arrayIndex",
+    input: "array preferred",
+    output: "array[arrayIndex] or identity fallback",
+    arrays: "primary behavior",
+    binary: "not intended",
+    mixedData: "not native",
+  },
+  "hookup.to/service/switch": {
+    modes: "identity",
+    config: "none",
+    input: "any",
+    output: "identity pass-through",
+    arrays: "pass-through",
+    binary: "pass-through",
+    mixedData: "not native",
+  },
+  "hookup.to/service/stats": {
+    modes: "feature extraction",
+    config: "property,features.{mean,std,max},copyProps",
+    input: "array of objects (or single object normalized to array)",
+    output: "[metaStats,...originalItems]",
+    arrays: "native",
+    binary: "not intended",
+    mixedData: "not native",
+  },
+  "hookup.to/service/board-service": {
+    modes: "saved-board runner or incoming-board preview",
+    config: "selectedBoard",
+    input: "board descriptor to preview OR runtime params to process",
+    output: "play result or preview acknowledgement",
+    arrays: "can process arrays item-by-item",
+    binary: "depends on target board services",
+    mixedData: "not native",
+  },
+};
+
+function normalizeSpec(spec?: ServicePromptSpec): Required<ServicePromptSpec> {
+  return {
+    modes: spec?.modes || DEFAULT_SPEC.modes,
+    config: spec?.config || DEFAULT_SPEC.config,
+    input: spec?.input || DEFAULT_SPEC.input,
+    output: spec?.output || DEFAULT_SPEC.output,
+    arrays: spec?.arrays || DEFAULT_SPEC.arrays,
+    binary: spec?.binary || DEFAULT_SPEC.binary,
+    mixedData: spec?.mixedData || DEFAULT_SPEC.mixedData,
+  };
+}
+
+function toServiceDocHeader(
+  serviceId: string,
+  serviceName: string,
+  spec?: ServicePromptSpec,
+) {
+  const normalized = normalizeSpec(spec);
+  return [
+    `[Service] ${serviceId}`,
+    `Name: ${serviceName}`,
+    `Modes: ${normalized.modes}`,
+    `Config: ${normalized.config}`,
+    `IO: in=${normalized.input} -> out=${normalized.output}`,
+    `Types: arrays=${normalized.arrays}; binary=${normalized.binary}; mixedData=${normalized.mixedData}`,
+  ];
+}
+
+function buildBrowserServiceHeaders(app: AppInstance): string[] {
+  const services = app
+    .listAvailableServices()
+    .map((svc) => ({
+      serviceId: svc.serviceId,
+      serviceName: svc.serviceName,
+    }))
+    .sort((a, b) => a.serviceId.localeCompare(b.serviceId));
+
+  return services.flatMap((svc, idx) => {
+    const header = toServiceDocHeader(
+      svc.serviceId,
+      svc.serviceName,
+      BROWSER_SERVICE_SPECS[svc.serviceId],
+    );
+    const separator = idx + 1 < services.length ? ["---"] : [];
+    return [...header, ...separator];
+  });
+}
+
+export function buildWorkflowSystemPrompt(app: AppInstance) {
+  const browserServiceHeaders = buildBrowserServiceHeaders(app);
+
+  return [
+    "You convert natural-language workflows into Readymade board JSON.",
+    "Return ONLY valid JSON (no markdown, no prose).",
+    "",
+    "Schema:",
+    '{"boardName":string,"runtimes":[{"id":string,"name":string,"type":"browser"|"rest"|"graphql","state"?:object,"url"?:string}],"services":{"<runtimeId>":[{"uuid":string,"serviceId":string,"serviceName":string,"state":object}]},"blocks"?:[{"id":string,"name":string,"serviceId":string,"serviceName":string,"state":object,"params"?:object}],"inputRouting"?:object,"outputRouting"?:object,"sidechainRouting"?:object}',
+    "",
+    "Block rules:",
+    '- A "blocks" entry defines a service once; a pipeline entry {"block":"<id>","uuid":string,"params"?:object} (nested: "instanceId" instead of "uuid") stands for that service, expanded when the board opens.',
+    '- Keep existing uses and definitions as they are unless the request is about them. To change what every use does, change the definition; to vary one use, set its "params", which the definition reads as {{param.<name>}}.',
+    "- A use's inside belongs to its definition: never write a block's services into a use.",
+    "",
+    "Planning rules:",
+    "- Use one or more runtimes when useful; do not force single-runtime boards.",
+    "- Runtime/service IDs must be unique where required.",
+    "- Service state must be practical and immediately runnable.",
+    "- Prefer explicit defaults over omitted critical fields.",
+    "",
+    "Data model rules:",
+    "- Browser services are generally JSON-first; some services accept/pass binary as opaque payloads.",
+    "- Array handling is service-specific; obey service notes below.",
+    "- MixedData is currently an hkp-rt concept (meta JSON + binary bytes).",
+    "",
+    "Browser service documentation headers:",
+    ...browserServiceHeaders,
+    "",
+    "hkp-rt service IDs:",
+    `- ${HKP_RT_SERVICES.join(",")}`,
+    "hkp-rt data types (high-level):",
+    "- json, string, binary, ringbuffer, MixedData(meta+binary), control-flow/custom wrappers",
+    "",
+    "hkp-node service IDs:",
+    `- ${HKP_NODE_SERVICES.join(",")}`,
+    "hkp-python service IDs:",
+    `- ${HKP_PYTHON_SERVICES.join(",")}`,
+  ].join("\n");
+}

package/bundle/hkp-frontend/src/runtime/browser/services/workflow-prompt/catalog/browser-service-specs.json

@@ -0,0 +1,110 @@
+{
+  "version": 1,
+  "services": {
+    "hookup.to/service/timer": {
+      "modes": ["periodic", "oneShot"],
+      "config": [
+        "periodic",
+        "periodicValue",
+        "periodicUnit",
+        "oneShotDelay",
+        "oneShotDelayUnit",
+        "running",
+        "start",
+        "stop",
+        "restart",
+        "immediate",
+        "until.triggerCount"
+      ],
+      "input": "any",
+      "output": "tick object with triggerCount plus optional passthrough payload",
+      "arrays": "generic",
+      "binary": "passthrough-in-delay"
+    },
+    "hookup.to/service/map": {
+      "modes": ["replace", "add", "overwrite", "sensingMode"],
+      "config": ["template", "mode", "sensingMode"],
+      "input": "object|array|scalar",
+      "output": "mapped object/scalar (null in sensingMode)",
+      "arrays": "maps each item",
+      "binary": "not-intended"
+    },
+    "hookup.to/service/filter": {
+      "modes": ["and", "or"],
+      "config": ["conditions", "aggregator"],
+      "input": "object|array",
+      "output": "input or null",
+      "arrays": "filters items",
+      "binary": "not-intended"
+    },
+    "hookup.to/service/buffer": {
+      "modes": ["capacity-flush", "interval-flush", "accumulatedOutput"],
+      "config": ["capacity", "interval", "accumulatedOutput", "action=clear"],
+      "input": "any",
+      "output": "array slice, full buffered array, or null",
+      "arrays": "concats arrays",
+      "binary": "opaque-ok"
+    },
+    "hookup.to/service/canvas": {
+      "modes": ["render", "capture"],
+      "config": [
+        "size",
+        "resizable",
+        "clearOnRedraw",
+        "fullscreen",
+        "capture",
+        "reportSizeUpdate"
+      ],
+      "input": "draw payload",
+      "output": "input passthrough or captured Blob",
+      "arrays": "passthrough",
+      "binary": "blob-output"
+    },
+    "hookup.to/service/monitor": {
+      "modes": ["observe"],
+      "config": ["logToConsole"],
+      "input": "any",
+      "output": "identity",
+      "arrays": "passthrough",
+      "binary": "inspectable"
+    },
+    "hookup.to/service/select": {
+      "modes": ["array-index"],
+      "config": ["arrayIndex"],
+      "input": "array",
+      "output": "selected value",
+      "arrays": "primary",
+      "binary": "not-intended"
+    },
+    "hookup.to/service/switch": {
+      "modes": ["identity"],
+      "config": [],
+      "input": "any",
+      "output": "identity",
+      "arrays": "passthrough",
+      "binary": "passthrough"
+    },
+    "hookup.to/service/stats": {
+      "modes": ["feature-extract"],
+      "config": [
+        "property",
+        "features.mean",
+        "features.std",
+        "features.max",
+        "copyProps"
+      ],
+      "input": "array<object>|object",
+      "output": "[metaStats,...input]",
+      "arrays": "native",
+      "binary": "not-intended"
+    },
+    "hookup.to/service/board-service": {
+      "modes": ["saved-board-run", "incoming-board-preview"],
+      "config": ["selectedBoard"],
+      "input": "boardDescriptor|runtimeParams",
+      "output": "play result or preview ack",
+      "arrays": "item-wise-run-supported",
+      "binary": "depends-on-board"
+    }
+  }
+}

package/bundle/hkp-frontend/src/runtime/browser/services/workflow-prompt/catalog/runtime-capabilities.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "runtimes": {
+    "browser": {
+      "defaultDataModel": "json-first",
+      "binarySupport": "service-dependent",
+      "mixedData": false,
+      "notes": [
+        "Most services operate on JS objects/arrays/scalars.",
+        "Some services can pass Blob/ArrayBuffer/Uint8Array as opaque payloads."
+      ]
+    },
+    "hkp-rt": {
+      "defaultDataModel": "variant",
+      "binarySupport": true,
+      "mixedData": true,
+      "mixedDataShape": {
+        "meta": "json",
+        "binary": "bytes"
+      },
+      "notes": [
+        "MixedData is native in hkp-rt.",
+        "Common payloads include json, string, binary, ringbuffer, mixedData."
+      ]
+    },
+    "hkp-node": {
+      "defaultDataModel": "json-first",
+      "binarySupport": "unknown-by-service",
+      "mixedData": false
+    },
+    "hkp-python": {
+      "defaultDataModel": "json-first",
+      "binarySupport": "unknown-by-service",
+      "mixedData": false
+    }
+  }
+}

package/bundle/hkp-frontend/src/runtime/browser/tests/asset-service.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+
+import BrowserRegistry from "hkp-frontend/src/runtime/browser/BrowserRegistry";
+import BrowserRuntimeApi from "hkp-frontend/src/runtime/browser/BrowserRuntimeApi";
+import { AssetDescriptor } from "hkp-frontend/src/runtime/board/assets";
+import { RuntimeDescriptor } from "hkp-frontend/src/types";
+
+/**
+ * The browser runtime's asset store is the board's `assets`: nothing is pushed
+ * to it, and a service resolves against the descriptors as they are when it
+ * runs — so an edit is what the next pass carries.
+ */
+
+const runtime: RuntimeDescriptor = { id: "ui", name: "Browser", type: "browser" };
+
+async function restoreWith(source: () => AssetDescriptor[], state: Record<string, unknown>) {
+  const result = await BrowserRuntimeApi.restoreRuntime(
+    runtime,
+    [{ uuid: "a", serviceId: "asset", serviceName: "Asset", state } as never],
+    null,
+    "Board",
+    source,
+  );
+  return result!.scope;
+}
+
+describe("the asset service in the browser", () => {
+  it("emits the board's asset as it is now", async () => {
+    let assets: AssetDescriptor[] = [{ id: "page", mediaType: "text/html", text: "v1" }];
+    const scope = await restoreWith(() => assets, { asset: "hkp-asset://page" });
+
+    expect(await BrowserRuntimeApi.processRuntime(scope, {}, null)).toEqual({
+      meta: { status: 200, contentType: "text/html", asset: "page", size: 2 },
+      body: "v1",
+    });
+
+    assets = [{ id: "page", mediaType: "text/html", text: "v2" }];
+    expect((await BrowserRuntimeApi.processRuntime(scope, {}, null)) as any).toMatchObject({
+      body: "v2",
+    });
+  });
+
+  it("emits bytes for content that is not text", async () => {
+    const scope = await restoreWith(
+      () => [{ id: "logo", mediaType: "image/png", base64: "AQID" }],
+      { asset: "hkp-asset://logo" },
+    );
+    const out = (await BrowserRuntimeApi.processRuntime(scope, {}, null)) as any;
+    expect([...out.binary]).toEqual([1, 2, 3]);
+  });
+
+  it("answers an undeclared asset with an error rather than its reference", async () => {
+    const scope = await restoreWith(() => [], { asset: "hkp-asset://missing" });
+    const out = (await BrowserRuntimeApi.processRuntime(scope, {}, null)) as any;
+    expect(out.meta.status).toBe(404);
+    expect(out.body.error).toMatch(/not declared/);
+  });
+
+  it("answers content that does not decode with an error", async () => {
+    const scope = await restoreWith(
+      () => [{ id: "logo", mediaType: "image/png", base64: "not base64!" }],
+      { asset: "hkp-asset://logo" },
+    );
+
+    const out = (await BrowserRuntimeApi.processRuntime(scope, {}, null)) as any;
+    expect(out.meta.status).toBe(404);
+    expect(out.body.error).toBe('asset "logo": its content is not base64');
+  });
+
+  it("is registered", () => {
+    expect(new BrowserRegistry().allServices().some((svc) => svc.serviceId === "asset")).toBe(true);
+  });
+});