my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/composables.ts

@@ -0,0 +1,129 @@
+// Vue bindings over the SDK models. Each model stays a plain object (no deep proxies); a version
+// counter bumps on every change so computed views re-evaluate once per frame.
+import { computed, ref, shallowRef, watch, type Ref } from "vue";
+import { AgentModel, NetworkModel, SessionModel } from "@sdk/models";
+import type { Activity, Frame } from "@sdk/api";
+import type { AppState } from "@sdk/app-state";
+import type { HubStream } from "./stream";
+
+export interface SessionTarget {
+  deviceId: string;
+  sessionId: string;
+}
+export interface AgentTarget extends SessionTarget {
+  agentId: number;
+}
+export type FeedStatus = "idle" | "connecting" | "live" | "reconnecting" | "fault";
+
+export const AGENT_DOCS = ["demo.job-runs", "demo.workspace"];
+export const agentSub = (t: AgentTarget) =>
+  `${t.deviceId}/agent/${t.sessionId}/${t.agentId}?docs=${AGENT_DOCS.join(",")}`;
+export const sessionSub = (t: SessionTarget) => `${t.deviceId}/session/${t.sessionId}`;
+export const deviceSub = (id: string) => `${id}/device?docs=app.shared-state`;
+
+/** Shared bookkeeping for one stream slot: hello → live, disconnected → reconnecting, fault. */
+function feed(
+  stream: HubStream,
+  slot: "device" | "session" | "agent",
+  apply: (frame: Frame) => void,
+  readyOn: "hello" | "snapshot" = "hello",
+) {
+  const status = ref<FeedStatus>("idle");
+  const fault = ref("");
+  stream.route(slot, (frame) => {
+    if (frame.type === "hello") {
+      status.value = readyOn === "hello" ? "live" : "connecting";
+      if (readyOn === "hello") fault.value = "";
+    } else if (frame.type === "disconnected") status.value = "reconnecting";
+    else if (frame.type === "fault") {
+      status.value = "fault";
+      fault.value = frame.error.message;
+    } else {
+      apply(frame);
+      if (frame.type === readyOn) {
+        fault.value = "";
+        status.value = "live";
+      }
+    }
+  });
+  const select = (key?: string) => {
+    fault.value = "";
+    status.value = key ? "connecting" : "idle";
+    stream.set(slot, key);
+  };
+  const retry = () => {
+    status.value = "connecting";
+    stream.reopen(slot);
+  };
+  return { status, fault, select, retry };
+}
+
+export function useNetwork(stream: HubStream) {
+  const model = new NetworkModel();
+  const version = ref(0);
+  model.subscribe(() => version.value++);
+  stream.onNetwork((devices) => model.apply({ type: "network", devices }));
+  const devices = computed(() => (version.value, model.devices));
+  const tree = computed(() => (version.value, model.tree()));
+  return { model, devices, tree };
+}
+
+export function useDevice(stream: HubStream, deviceId: Ref<string | undefined>) {
+  const sharedState = shallowRef<{ value: AppState; revision: number }>();
+  const activity = shallowRef<Activity[]>([]);
+  const { status, select } = feed(stream, "device", (frame) => {
+    if (frame.type === "doc" && frame.kind === "app.shared-state")
+      sharedState.value = { value: frame.value as AppState, revision: frame.revision ?? 0 };
+    else if (frame.type === "activity")
+      activity.value = [...activity.value, ...frame.items].slice(-50);
+  });
+  watch(
+    deviceId,
+    (id) => {
+      sharedState.value = undefined;
+      select(id ? deviceSub(id) : undefined);
+    },
+    { immediate: true },
+  );
+  return { sharedState, activity, status };
+}
+
+export function useSession(stream: HubStream, target: Ref<SessionTarget | undefined>) {
+  const model = new SessionModel();
+  const version = ref(0);
+  model.subscribe(() => version.value++);
+  const { status, fault, select } = feed(stream, "session", (frame) => model.apply(frame));
+  watch(
+    () => (target.value ? sessionSub(target.value) : undefined),
+    (key) => {
+      model.clear();
+      select(key);
+    },
+    { immediate: true },
+  );
+  const state = computed(() => (version.value, model.state));
+  return { model, state, status, fault };
+}
+
+export function useAgent(stream: HubStream, target: Ref<AgentTarget | undefined>) {
+  const model = new AgentModel();
+  const version = ref(0);
+  model.subscribe(() => version.value++);
+  const { status, fault, select, retry } = feed(
+    stream,
+    "agent",
+    (frame) => model.apply(frame),
+    "snapshot",
+  );
+  watch(
+    () => (target.value ? agentSub(target.value) : undefined),
+    (key) => {
+      model.clear();
+      select(key);
+    },
+    { immediate: true },
+  );
+  // A fresh object per version: the model mutates its state in place.
+  const state = computed(() => (version.value, { ...model.state }));
+  return { model, state, status, fault, version, retry };
+}

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/hub.ts

@@ -0,0 +1,40 @@
+// Commands. Device calls go through the hub proxy (it injects the token, so the browser never
+// holds one); status checks and UI state go to the hub itself.
+import { DpiClient } from "@sdk/client";
+import { DpiError } from "@sdk/errors";
+import type { ErrorCode, NetworkDevice } from "@sdk/api";
+
+export const deviceClient = (id: string) => new DpiClient(`/api/devices/${encodeURIComponent(id)}`);
+
+async function call<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const r = await fetch(`/api${path}`, {
+    method,
+    headers: body === undefined ? {} : { "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const data = await r.json().catch(() => undefined);
+  if (!r.ok) {
+    const error = (data as { error?: { code?: ErrorCode; message?: string } } | undefined)?.error;
+    throw new DpiError(
+      error?.code ?? "internal",
+      error?.message ?? `${r.status} ${r.statusText}`,
+      r.status,
+    );
+  }
+  return data as T;
+}
+
+export const hub = {
+  network: () => call<{ configFile?: string; devices: NetworkDevice[] }>("GET", "/network"),
+  /** Probe a device now. Devices themselves are configured in dpi-network.yaml, not here. */
+  check: (id: string) =>
+    call<NetworkDevice>("POST", `/devices/${encodeURIComponent(id)}/check`, {}),
+  async uiGet<T>(key: string): Promise<T | undefined> {
+    return ((await call<{ value: T | null }>("GET", `/ui-state/${encodeURIComponent(key)}`))
+      .value ?? undefined) as T | undefined;
+  },
+  uiSet: (key: string, value: unknown) =>
+    call<{ ok: true }>("PUT", `/ui-state/${encodeURIComponent(key)}`, { value }),
+};
+
+export const message = (e: unknown) => (e instanceof Error ? e.message : String(e));

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/icon-path.ts

@@ -0,0 +1,7 @@
+const DEFAULT_ICON = "lab.png";
+
+/** The icon name is device-controlled; only a plain png/svg file name may become part of the path. */
+export function iconPath(name?: unknown) {
+  const ok = typeof name === "string" && /^[\w.-]+\.(png|svg)$/.test(name) && !name.includes("..");
+  return `/icons/${ok ? name : DEFAULT_ICON}`;
+}

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/ids.ts

@@ -0,0 +1,2 @@
+export const newId = (): string =>
+  globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/jobs.ts

@@ -0,0 +1,80 @@
+// Durable jobs in the web client: the device's job definitions, this agent's runs (the `demo.job-runs`
+// document), and the actions a run card or the Tasks tab can take.
+import { computed, ref } from "vue";
+import { JOB_RUNS_DOC, type JobDef, type JobRun, type JobRunsDoc } from "@sdk/jobs";
+import {
+  agentHandle,
+  agentState,
+  attempt,
+  device,
+  hideInspector,
+  narrow,
+  notify,
+  select,
+  selected,
+  sessionHandle,
+} from "./store";
+
+export const jobDefs = computed<JobDef[]>(() => device.value?.info?.jobs ?? []);
+export const jobDef = (id: string) => jobDefs.value.find((d) => d.id === id);
+
+/** This agent's runs, newest first. */
+export const jobRuns = computed<JobRun[]>(() => {
+  const doc = agentState.value.docs[JOB_RUNS_DOC] as JobRunsDoc | undefined;
+  return Object.values(doc?.items ?? {}).sort((a, b) => b.id - a.id);
+});
+export const runById = (id: number) => jobRuns.value.find((r) => r.id === id);
+export const runByCall = (callId: string) => jobRuns.value.find((r) => r.toolCallId === callId);
+
+/** One clock for every elapsed timer on the page. */
+export const now = ref(Date.now());
+setInterval(() => (now.value = Date.now()), 1000);
+
+export const seconds = (ms: number) =>
+  ms < 1000
+    ? `${Math.max(0, Math.round(ms))}ms`
+    : ms < 60_000
+      ? `${(ms / 1000).toFixed(1)}s`
+      : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
+
+export const pending = ref<string>();
+
+async function act<T>(key: string, fn: () => Promise<T>): Promise<T | undefined> {
+  if (pending.value) return;
+  pending.value = key;
+  try {
+    return await attempt(fn);
+  } finally {
+    pending.value = undefined;
+  }
+}
+
+/** Scroll the chat to a run's card (it renders where the run started). */
+export function revealRun(id: number) {
+  if (narrow.value) hideInspector();
+  setTimeout(() =>
+    document
+      .querySelector(`[data-job-run="${id}"]`)
+      ?.scrollIntoView({ behavior: "smooth", block: "center" }),
+  );
+}
+
+export async function startJob(def: JobDef) {
+  const started = await act(`start:${def.id}`, () =>
+    agentHandle.value!.demo<{ taskId: number }>("jobs", { job: def.id }),
+  );
+  if (started) {
+    notify(`${def.title} started. It runs in the chat.`);
+    revealRun(started.taskId);
+  }
+}
+
+export const decide = (run: JobRun, approved: boolean) =>
+  act(`decide:${run.id}`, () => agentHandle.value!.demo(`jobs/${run.id}/approval`, { approved }));
+
+export const stopRun = (run: JobRun) =>
+  act(`stop:${run.id}`, () => sessionHandle.value!.abortTask(run.id));
+
+export function openAgent(conversationId: number) {
+  if (selected.value) select({ ...selected.value, agentId: conversationId });
+}

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/link-policy.ts

@@ -0,0 +1,16 @@
+/**
+ * Transcript text is written by a device (or by an agent a device can prompt-inject)
+ * and is rendered inside the hub's own origin. A link in it must therefore never lead
+ * back into the hub: one click is a top-level navigation to a hub path under the
+ * operator's credentials. Only absolute http(s) links to OTHER origins survive.
+ */
+export function externalHref(href: string, hubOrigin: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(href.trim()); // no base: relative and protocol-relative forms throw and are dropped
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  return url.origin === hubOrigin ? null : url.href;
+}

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/markdown-policy.ts

@@ -0,0 +1,115 @@
+// What survives sanitising of transcript markdown. The text is written by a device or by an agent
+// a device can prompt-inject, and it is rendered inside the admin origin: anything beyond the
+// markdown subset (styles, forms, overlays, remote images) is an injection or phishing surface.
+
+export const ALLOWED_TAGS = [
+  "p",
+  "br",
+  "hr",
+  "strong",
+  "b",
+  "em",
+  "i",
+  "del",
+  "s",
+  "code",
+  "pre",
+  "blockquote",
+  "ul",
+  "ol",
+  "li",
+  "a",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "small",
+  "sub",
+  "sup",
+  "table",
+  "thead",
+  "tbody",
+  "tr",
+  "th",
+  "td",
+  "img",
+  // Only the disabled GFM task-list checkbox; anything else is removed by the attribute policy.
+  "input",
+];
+
+export const FORBIDDEN_TAGS = [
+  "form",
+  "style",
+  "script",
+  "button",
+  "select",
+  "textarea",
+  "iframe",
+  "object",
+  "embed",
+  "svg",
+  "math",
+];
+
+const ATTRIBUTES: Record<string, readonly string[]> = {
+  a: ["href", "title"],
+  img: ["src", "alt", "title"],
+  th: ["colspan", "rowspan", "align"],
+  td: ["colspan", "rowspan", "align"],
+  ol: ["start"],
+  code: ["class"],
+  input: ["type", "checked", "disabled"],
+};
+
+export const ALLOWED_ATTR = [...new Set(Object.values(ATTRIBUTES).flat())];
+
+const CODE_CLASS = /^language-[\w-]+$/;
+const DIGITS = /^\d{1,4}$/;
+const ALIGN = /^(left|right|center)$/i;
+
+export function attributeAllowed(tag: string, name: string, value: string): boolean {
+  if (!Object.hasOwn(ATTRIBUTES, tag) || !ATTRIBUTES[tag].includes(name)) return false;
+  switch (name) {
+    case "class":
+      return CODE_CLASS.test(value);
+    case "type":
+      return value.toLowerCase() === "checkbox";
+    case "colspan":
+    case "rowspan":
+    case "start":
+      return DIGITS.test(value);
+    case "align":
+      return ALIGN.test(value);
+    default:
+      return true;
+  }
+}
+
+const RASTER_DATA_URI = /^data:image\/(png|jpeg|gif|webp);base64,[A-Za-z0-9+/]+={0,2}$/i;
+
+// Express matches routes case-insensitively, so /API/... reaches the same handlers.
+const ADMIN_API_PATH = /^\/api(\/|$)/i;
+
+/**
+ * A remote image is a tracking channel: agent output can encode data in its URL. Only an image
+ * served by the hub's static files or embedded in the text is kept; the admin API is not an
+ * image host. The WHATWG parser decides what a browser would request, so tab, backslash, `//`
+ * and dot-segment tricks resolve to their real origin and path.
+ */
+export function isSafeImageSrc(src: string, hubOrigin: string): boolean {
+  if (RASTER_DATA_URI.test(src)) return true;
+  if (!src.trim()) return false;
+  let url: URL;
+  try {
+    url = new URL(src, hubOrigin);
+  } catch {
+    return false;
+  }
+  return (
+    (url.protocol === "https:" || url.protocol === "http:") &&
+    url.origin === hubOrigin &&
+    !ADMIN_API_PATH.test(url.pathname)
+  );
+}

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/markdown.ts

@@ -0,0 +1,60 @@
+import { marked } from "marked";
+import DOMPurify from "dompurify";
+import { externalHref } from "./link-policy";
+import {
+  ALLOWED_ATTR,
+  ALLOWED_TAGS,
+  FORBIDDEN_TAGS,
+  attributeAllowed,
+  isSafeImageSrc,
+} from "./markdown-policy";
+
+// DOMPurify only exists with a DOM; SSR and unit tests import this module without one.
+if (DOMPurify.isSupported) {
+  DOMPurify.addHook("afterSanitizeAttributes", (node) => {
+    const tag = node.nodeName.toLowerCase();
+    // The tag allowlist is global; which attributes an element may keep is decided per element.
+    for (const { name, value } of Array.from(node.attributes))
+      if (!attributeAllowed(tag, name, value)) node.removeAttribute(name);
+    if (tag === "img" && !isSafeImageSrc(node.getAttribute("src") ?? "", location.origin)) {
+      node.replaceWith(document.createTextNode(node.getAttribute("alt") ?? ""));
+      return;
+    }
+    if (tag === "input") {
+      if (node.getAttribute("type") === null) node.remove();
+      else node.setAttribute("disabled", "");
+      return;
+    }
+    if (tag !== "a") return;
+    const href = node.getAttribute("href");
+    const safe = href === null ? null : externalHref(href, location.origin);
+    if (safe) {
+      node.setAttribute("href", safe);
+      node.setAttribute("target", "_blank");
+      node.setAttribute("rel", "noopener noreferrer");
+    } else {
+      node.removeAttribute("href");
+      node.removeAttribute("target");
+    }
+  });
+}
+
+const SANITIZE = {
+  ALLOWED_TAGS,
+  ALLOWED_ATTR,
+  FORBID_TAGS: FORBIDDEN_TAGS,
+  ALLOW_DATA_ATTR: false,
+  ALLOW_ARIA_ATTR: false,
+};
+
+// Transcripts re-render on every stream frame; cache rendered blocks by their source text.
+const cache = new Map<string, string>();
+export function markdown(text: string) {
+  let html = cache.get(text);
+  if (html === undefined) {
+    html = DOMPurify.sanitize(marked.parse(text, { async: false }) as string, SANITIZE);
+    if (cache.size > 400) cache.delete(cache.keys().next().value!);
+    cache.set(text, html);
+  }
+  return html;
+}

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/pair-close.ts

@@ -0,0 +1,23 @@
+export type CancelResult = "cancelled" | "issued" | "failed";
+
+export const CANCEL_TIMEOUT_MS = 4000;
+
+/**
+ * Cancel the live code first, but never let a failing or hanging request keep the wizard open:
+ * an unconfirmed code simply expires on the hub. Only a code the device already redeemed
+ * keeps the wizard open, so the operator sees it and can revoke it explicitly.
+ */
+export async function closeWizard(opts: {
+  needsCancel: boolean;
+  cancel: () => Promise<CancelResult>;
+  timeoutMs: number;
+}): Promise<{ closed: boolean; confirmed: boolean }> {
+  if (!opts.needsCancel) return { closed: true, confirmed: true };
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const result = await Promise.race<CancelResult>([
+    opts.cancel().catch((): CancelResult => "failed"),
+    new Promise<CancelResult>((done) => (timer = setTimeout(() => done("failed"), opts.timeoutMs))),
+  ]);
+  clearTimeout(timer);
+  return { closed: result !== "issued", confirmed: result === "cancelled" };
+}

package/apps/dpi-playground/apps/dpi-playground-fe/src/client/pair-handoff.ts

@@ -0,0 +1,56 @@
+/** Pair links stay in RAM and may only refer to the browser's own hub. */
+export type PairHandoff = { code: string; origin: string } | { error: string };
+
+export function readPairHandoff(url: URL): PairHandoff | undefined {
+  if (!/^\/pair\/?$/.test(url.pathname)) return undefined;
+  const params = url.searchParams;
+  if (!params.has("code") && !params.has("origin") && !params.has("v")) return undefined;
+  const code = params.get("code");
+  if (
+    url.username ||
+    url.password ||
+    url.hash ||
+    params.getAll("code").length !== 1 ||
+    !code ||
+    !/^[A-Z2-7]{8}$/.test(code) ||
+    params.getAll("v").length !== 1 ||
+    params.get("v") !== "1"
+  ) {
+    return { error: "Invalid pairing link. Use a complete version 1 link from the hub wizard." };
+  }
+  if (params.has("origin")) {
+    try {
+      const origin = new URL(params.get("origin")!);
+      if (
+        params.getAll("origin").length !== 1 ||
+        origin.origin !== url.origin ||
+        origin.pathname !== "/" ||
+        origin.username ||
+        origin.password ||
+        origin.search ||
+        origin.hash
+      )
+        throw Error("origin mismatch");
+    } catch {
+      return {
+        error: "This pairing link does not belong to this hub. Open the original hub link instead.",
+      };
+    }
+  }
+  return { code, origin: url.origin };
+}
+
+/**
+ * The scrubbed /pair URL would still open the wizard, and mint a fresh code, on reload.
+ * Returns the path to replace it with, or undefined when the URL is not a pair URL.
+ */
+export const settledPairPath = (url: URL): string | undefined =>
+  /^\/pair\/?$/.test(url.pathname) ? "/" : undefined;
+
+/**
+ * A bare /pair URL has no handoff to resume: re-opening the wizard there would
+ * mint a fresh pairing code on every reload. Go home instead — the admin
+ * sidebar button remains the only way to start a pairing without a link.
+ */
+export const barePairHome = (url: URL): string | undefined =>
+  /^\/pair\/?$/.test(url.pathname) && readPairHandoff(url) === undefined ? "/" : undefined;