@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.1

package/src/performance/timeline.ts

@@ -0,0 +1,100 @@
+import { ObservabilityStore } from "@ericsanchezok/synergy-harness/observability/store"
+import { PerformanceCatalog } from "./catalog"
+import { ObservabilityConfig } from "@ericsanchezok/synergy-harness/observability/config"
+import { PerformanceError } from "./error"
+import { PerformanceSchema } from "./schema"
+
+export namespace PerformanceTimeline {
+  export async function get(query: PerformanceSchema.TimelineQuery): Promise<PerformanceSchema.Timeline> {
+    const now = Date.now()
+    const to = parseTime(query.to, now)
+    const from = parseTime(query.from, query.windowMs ? to - query.windowMs : to - 15 * 60 * 1000)
+    if (from >= to) throw new PerformanceError("PERF_INVALID_QUERY", "Timeline from must be before to.", 400)
+
+    const config = ObservabilityConfig.current()
+    const bucketMs = query.bucketMs ?? Math.max(1000, Math.floor((to - from) / config.maxTimelineBuckets) + 1)
+    const bucketCount = Math.floor((to - from) / bucketMs) + 1
+    if (bucketCount > config.maxTimelineBuckets) {
+      throw new PerformanceError("PERF_TOO_MANY_BUCKETS", "Timeline query exceeds the configured bucket limit.", 400, {
+        maxBuckets: config.maxTimelineBuckets,
+        bucketCount,
+      })
+    }
+
+    const metrics = normalizeMetrics(query.metric)
+    const buckets = bucketStarts(from, to, bucketMs)
+    const series = await Promise.all(
+      metrics.map(async (name) => {
+        const info = PerformanceCatalog.get(name)
+        if (!info) throw new PerformanceError("PERF_INVALID_QUERY", "Timeline metric is not allowed.", 400)
+        const stat = query.stat ?? info.defaultStat
+        const rows = await ObservabilityStore.queryMetricBuckets({
+          since: from,
+          until: to,
+          names: [name],
+          module: query.module,
+          scopeID: query.scopeID,
+          sessionID: query.sessionID,
+          tool: query.tool,
+          providerID: query.providerID,
+          bucketMs,
+        })
+        const bucketed = new Map(rows.map((row) => [row.bucket, row]))
+        const points = buckets.map((time, index) => {
+          const bucket = bucketed.get(index)
+          return {
+            time,
+            value: bucket ? (stat === "rate" ? bucket.sum / Math.max(1, bucketMs / 1000) : bucket[stat]) : null,
+            sampleCount: bucket?.count ?? 0,
+          }
+        })
+        const sampleCount = points.reduce((total, point) => total + (point.sampleCount ?? 0), 0)
+        return PerformanceSchema.TimelineSeries.parse({
+          name,
+          label: info.label,
+          unit: info.unit,
+          kind: info.kind,
+          stat,
+          sampleCount,
+          module: info.module,
+          source: info.source,
+          points,
+        })
+      }),
+    )
+    return PerformanceSchema.Timeline.parse({
+      generatedAt: new Date().toISOString(),
+      from,
+      to,
+      bucketMs,
+      series,
+    })
+  }
+
+  function parseTime(value: string | undefined, fallback: number) {
+    if (!value) return fallback
+    const parsed = Date.parse(value)
+    if (!Number.isFinite(parsed)) throw new PerformanceError("PERF_INVALID_QUERY", "Invalid timeline time range.", 400)
+    return parsed
+  }
+
+  function normalizeMetrics(metric: string | string[] | undefined) {
+    const requested = Array.isArray(metric) ? metric : metric ? [metric] : PerformanceCatalog.defaultMetricNames
+    const resolved = requested.map((name) => PerformanceCatalog.resolveName(name))
+    const unique = [...new Set(resolved)]
+    const invalid = unique.filter((name) => !PerformanceCatalog.get(name))
+    if (invalid.length)
+      throw new PerformanceError("PERF_INVALID_QUERY", "Timeline metric is not allowed.", 400, {
+        invalidMetrics: invalid,
+      })
+    return unique
+  }
+
+  function bucketStarts(from: number, to: number, bucketMs: number) {
+    const buckets: number[] = []
+    for (let bucket = from; bucket <= to; bucket += bucketMs) buckets.push(bucket)
+    return buckets
+  }
+
+  export const allowedMetricNames = PerformanceCatalog.allMetricNames()
+}

package/src/performance/trace-detail.ts

@@ -0,0 +1,97 @@
+import { Observability } from "@ericsanchezok/synergy-harness/observability"
+import { ObservabilityStore } from "@ericsanchezok/synergy-harness/observability/store"
+import { PerformanceError } from "./error"
+import { PerformanceProjection } from "./projection"
+import { PerformanceSchema } from "./schema"
+import { parseJson } from "@ericsanchezok/synergy-harness/util/json-parse"
+
+export namespace PerformanceTraceDetail {
+  export function list(query: PerformanceSchema.TraceListQuery): PerformanceSchema.TraceList {
+    const since = query.from ? Date.parse(query.from) : Date.now() - 15 * 60 * 1000
+    const until = query.to ? Date.parse(query.to) : undefined
+    const baseLimit = query.limit ?? 50
+    const rows = ObservabilityStore.querySpans({
+      since: Number.isFinite(since) ? since : undefined,
+      until: until !== undefined && Number.isFinite(until) ? until : undefined,
+      limit: baseLimit,
+      minDurationMs: query.minDurationMs,
+      status: query.status,
+      scopeID: query.scopeID,
+      sessionID: query.sessionID,
+      kinds: query.kind ? PerformanceProjection.spanKinds(query.kind) : undefined,
+      distinctTrace: true,
+    })
+    return PerformanceSchema.TraceList.parse({
+      generatedAt: new Date().toISOString(),
+      items: rows.map(PerformanceProjection.traceRow),
+    })
+  }
+
+  export async function detail(
+    traceId: string,
+    opts: { maxEvents?: number; includeEvents?: boolean; includeAttributes?: boolean } = {},
+  ): Promise<PerformanceSchema.TraceDetail> {
+    const spans = ObservabilityStore.querySpans({ traceId, limit: 10_000 }).sort((a, b) => a.start_time - b.start_time)
+    const events =
+      opts.includeEvents === false
+        ? []
+        : (await Observability.query({ traceId, limit: opts.maxEvents ?? 500 })).map(projectEvent)
+    if (!spans.length && !events.length)
+      throw new PerformanceError("PERF_TRACE_NOT_FOUND", "Performance trace was not found.", 404, { traceId })
+    const parsed = spans.map((row) =>
+      PerformanceSchema.Span.parse({
+        traceId: row.trace_id,
+        correlationId: row.correlation_id ?? undefined,
+        spanId: row.span_id,
+        parentSpanId: row.parent_span_id ?? undefined,
+        kind: row.kind,
+        name: row.name,
+        module: row.module,
+        source: row.source,
+        startTime: row.start_time,
+        endTime: row.end_time ?? undefined,
+        durationMs: row.duration_ms ?? undefined,
+        status: row.status,
+        lastActivityTime: row.last_activity_time ?? undefined,
+        heartbeatTime: row.heartbeat_time ?? undefined,
+        heartbeatCount: row.heartbeat_count ?? undefined,
+        stalled: row.stalled ? true : undefined,
+        errorCode: row.error_code ?? undefined,
+        errorMessage: row.error_message ?? undefined,
+        sessionID: row.session_id ?? undefined,
+        scopeID: row.scope_id ?? undefined,
+        rid: row.rid ?? undefined,
+        tool: row.tool ?? undefined,
+        attributes: opts.includeAttributes === false ? {} : parseJson(row.attributes_json),
+      }),
+    )
+    return PerformanceSchema.TraceDetail.parse({
+      generatedAt: new Date().toISOString(),
+      traceId,
+      root: parsed.find((span) => !span.parentSpanId) ?? parsed[0],
+      spans: parsed,
+      events,
+      redaction: { applied: true, omittedAttributes: opts.includeAttributes === false ? parsed.length : 0 },
+    })
+  }
+
+  function projectEvent(event: Observability.Event): PerformanceSchema.TraceEvent {
+    return PerformanceSchema.TraceEvent.parse({
+      time: event.time,
+      iso: event.iso,
+      type: event.type,
+      level: event.level,
+      traceId: event.traceId,
+      correlationId: event.correlationId,
+      sessionID: event.sessionID,
+      messageID: event.messageID,
+      callID: event.callID,
+      rid: event.rid,
+      tool: event.tool,
+      processId: event.processId,
+      pid: event.pid,
+      dataKeys: event.data && typeof event.data === "object" ? Object.keys(event.data).slice(0, 24) : [],
+      redactionApplied: event.redaction.applied,
+    })
+  }
+}

package/src/presentation/service.ts

@@ -0,0 +1,303 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context"
+import { createHash } from "node:crypto"
+import type { Server } from "@ericsanchezok/synergy-server/server/server"
+import { ResourceReference } from "@ericsanchezok/synergy-util/resource-reference"
+import { WorkbenchView } from "@ericsanchezok/synergy-util/workbench-view"
+
+export namespace WorkbenchPresentation {
+  export const DEFAULT_TIMEOUT_SECONDS = 30
+  export type Caller = {
+    scopeID: string
+    sessionID: string
+    requestId: string
+    context?: ResourceReference.Context
+    signal: AbortSignal
+  }
+  type Attempt = {
+    signature: string
+    caller: Pick<Caller, "scopeID" | "sessionID" | "requestId">
+    command?: WorkbenchView.Command
+    target?: WorkbenchView.Target
+    promise: Promise<WorkbenchView.Result>
+    result?: WorkbenchView.Result
+    receipt: boolean
+    settle?: (outcome: WorkbenchView.Outcome) => void
+    cancel?: (reason: string) => void
+  }
+  type Client = {
+    clientId: string
+    send: (frame: Server.EventClientFrame) => boolean
+    targets?: Set<WorkbenchView.TargetKind>
+    active?: Server.EventClientActive
+    attempts: Map<string, Attempt>
+    views: Map<string, WorkbenchView.View>
+  }
+  const state = RuntimeContext.state(() => ({
+    clients: new Map<string, Client>(),
+    attempts: new Map<string, Attempt>(),
+    disposed: false,
+  }))
+  const key = (caller: Pick<Caller, "scopeID" | "sessionID" | "requestId">) =>
+    JSON.stringify([caller.scopeID, caller.sessionID, caller.requestId])
+  const unknown = (reason: string): WorkbenchView.Outcome => ({ status: "unknown", reason })
+  function targetIdentity(target: WorkbenchView.Target): string {
+    const id =
+      target.kind === "note"
+        ? target.id
+        : target.kind === "workspace-file"
+          ? target.path
+          : target.kind === "browser-page"
+            ? target.pageId
+            : target.url
+    return JSON.stringify([target.kind, id])
+  }
+
+  export function init(): () => void {
+    const instance = state()
+    return () => {
+      if (instance.disposed) return
+      instance.disposed = true
+      for (const client of instance.clients.values()) {
+        for (const attempt of client.attempts.values())
+          attempt.cancel?.("The Runtime is closing; no receipt confirms the effect.")
+        client.attempts.clear()
+        client.views.clear()
+      }
+      instance.clients.clear()
+      instance.attempts.clear()
+    }
+  }
+
+  export function contribution(): Server.EventClientContribution {
+    const instance = state()
+    return {
+      connect({ clientId, send }) {
+        const client: Client = { clientId, send, attempts: new Map(), views: new Map() }
+        if (!instance.disposed) instance.clients.set(clientId, client)
+        let disposed = instance.disposed
+        return {
+          receive(payload) {
+            if (disposed || instance.disposed) return
+            const parsed = WorkbenchView.ClientMessage.safeParse(payload)
+            if (!parsed.success) return
+            const message = parsed.data
+            if (message.type === "client.workbench.ready") {
+              client.targets = new Set(message.properties.targets)
+              for (const attempt of client.attempts.values())
+                if (attempt.command?.action === "open" && !client.targets.has(attempt.command.target.kind))
+                  attempt.cancel?.("The frontend no longer supports this target; no receipt confirms the effect.")
+              return
+            }
+            if (!client.active) return
+            const attempt = client.attempts.get(key({ ...client.active, requestId: message.properties.requestId }))
+            if (!attempt?.settle) return
+            const outcome = message.properties.outcome
+            if (outcome.status === "applied") {
+              const views = outcome.views ?? []
+              if (new Set(views.map((view) => view.viewId)).size !== views.length) return
+              const command = attempt.command
+              if (!command) return
+              const target = attempt.target
+              if (
+                command.action === "open" &&
+                (!target ||
+                  !views.some((view) => view.visible && targetIdentity(view.target) === targetIdentity(target)))
+              )
+                return
+              if (
+                command.action === "hide" &&
+                (!target ||
+                  !views.some(
+                    (view) =>
+                      view.viewId === command.viewId &&
+                      !view.visible &&
+                      targetIdentity(view.target) === targetIdentity(target),
+                  ))
+              )
+                return
+              if (command.action === "status") client.views.clear()
+              for (const view of views) client.views.set(view.viewId, view)
+            }
+            attempt.receipt = true
+            attempt.settle(outcome)
+          },
+          active(active) {
+            if (disposed || instance.disposed) return
+            const previous = client.active
+            client.active = active
+            if (
+              previous?.scopeID === active?.scopeID &&
+              previous?.sessionID === active?.sessionID &&
+              previous?.generation === active?.generation
+            )
+              return
+            for (const attempt of client.attempts.values())
+              attempt.cancel?.("The frontend changed its active view; no receipt confirms the effect.")
+            client.views.clear()
+          },
+          dispose() {
+            if (disposed) return
+            disposed = true
+            instance.clients.delete(clientId)
+            for (const attempt of client.attempts.values()) {
+              attempt.settle?.(unknown("The frontend disconnected; no receipt confirms the effect."))
+              attempt.receipt = false
+              attempt.result = {
+                requestId: attempt.caller.requestId,
+                ...unknown("The original frontend connection is gone; its receipt is no longer retained."),
+              }
+              attempt.promise = Promise.resolve(attempt.result)
+            }
+            client.attempts.clear()
+            client.views.clear()
+            client.targets = undefined
+            client.active = undefined
+          },
+        }
+      },
+    }
+  }
+
+  export function request(parameters: WorkbenchView.Parameters, caller: Caller): Promise<WorkbenchView.Result> {
+    const instance = state()
+    const { input, clientId } = parameters
+    if (input.action === "status" && input.requestId) {
+      const attempt = instance.attempts.get(key({ ...caller, requestId: input.requestId }))
+      return Promise.resolve(
+        attempt?.receipt && attempt.result
+          ? attempt.result
+          : { requestId: input.requestId, ...unknown("No confirmed receipt is retained for this Scope and Session.") },
+      )
+    }
+    const signature = createHash("sha256")
+      .update(JSON.stringify({ parameters, context: caller.context }))
+      .digest("hex")
+    const identity = { scopeID: caller.scopeID, sessionID: caller.sessionID, requestId: caller.requestId }
+    const existing = instance.attempts.get(key(caller))
+    if (existing)
+      return existing.signature === signature
+        ? existing.result
+          ? Promise.resolve(existing.result)
+          : existing.promise
+        : Promise.resolve({
+            requestId: caller.requestId,
+            status: "blocked",
+            reason: "This tool call identity already has different arguments; it cannot be reused.",
+          })
+    const immediate = (outcome: WorkbenchView.Outcome) => {
+      const result = { requestId: caller.requestId, ...outcome }
+      const promise = Promise.resolve(result)
+      if (!instance.disposed)
+        instance.attempts.set(key(caller), { caller: identity, signature, promise, result, receipt: false })
+      return promise
+    }
+    if (caller.signal.aborted) return immediate({ status: "cancelled", reason: "Cancelled before dispatch." })
+    if (instance.disposed)
+      return immediate({ status: "unavailable", reason: "The Workbench presentation service is closed." })
+    if (input.action === "open" && input.target.kind === "workspace-file" && caller.context?.state !== "bound")
+      return immediate({
+        status: "blocked",
+        reason:
+          "Opening a Workspace file requires the caller Session's captured valid Workspace; a viewer's Workspace cannot be used.",
+      })
+    let target = input.action === "open" ? input.target : undefined
+    if (target?.kind === "workspace-file") {
+      const relative = ResourceReference.resolvePath(target.path, caller.context ?? { state: "none" })
+      if (!relative)
+        return immediate({ status: "blocked", reason: "The file is not inside the caller's captured Workspace." })
+      target = { ...target, path: relative }
+    }
+    const clients = [...instance.clients.values()].filter(
+      (client) =>
+        client.active?.scopeID === caller.scopeID &&
+        client.active.sessionID === caller.sessionID &&
+        client.targets?.size &&
+        (input.action !== "open" || client.targets.has(input.target.kind)),
+    )
+    const selected = clientId
+      ? clients.find((client) => client.clientId === clientId)
+      : clients.length === 1
+        ? clients[0]
+        : undefined
+    if (!selected) {
+      if (!clientId && clients.length > 1)
+        return immediate({
+          status: "ambiguous",
+          reason: "Multiple eligible frontends show this Session. Choose a returned clientId; nothing was dispatched.",
+          clients: clients.map((client) => ({ clientId: client.clientId })),
+        })
+      return immediate({
+        status: "unavailable",
+        reason: clientId
+          ? "The selected clientId is not a ready, supported frontend actively showing this Scope and Session."
+          : "No ready frontend supporting this target is actively showing this Scope and Session.",
+      })
+    }
+    if (input.action === "hide") target = selected.views.get(input.viewId)?.target
+    if (input.action === "hide" && !target)
+      return immediate({
+        status: "blocked",
+        reason: "The selected frontend has no confirmed view with this viewId. Query current views before hiding it.",
+      })
+    let resolve!: (result: WorkbenchView.Result) => void
+    const promise = new Promise<WorkbenchView.Result>((done) => {
+      resolve = done
+    })
+    const attempt: Attempt = { caller: identity, command: input, target, signature, promise, receipt: false }
+    instance.attempts.set(key(caller), attempt)
+    selected.attempts.set(key(caller), attempt)
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const aborted = () =>
+      attempt.cancel?.("Cancelled after dispatch; without a frontend receipt the effect is unknown.")
+    attempt.settle = (outcome) => {
+      if (!attempt.settle) return
+      clearTimeout(timer)
+      caller.signal.removeEventListener("abort", aborted)
+      attempt.settle = undefined
+      attempt.cancel = undefined
+      attempt.command = undefined
+      attempt.target = undefined
+      attempt.result = { requestId: caller.requestId, clientId: selected.clientId, ...outcome }
+      resolve(attempt.result)
+    }
+    attempt.cancel = (reason) => {
+      attempt.settle?.(unknown(reason))
+      selected.send({
+        scopeID: caller.scopeID,
+        payload: { type: "server.workbench.cancel", properties: { requestId: caller.requestId } },
+      })
+    }
+    caller.signal.addEventListener("abort", aborted, { once: true })
+    const deadline = performance.now() + (parameters.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000
+    const wait = () => {
+      const remaining = deadline - performance.now()
+      if (remaining <= 0) {
+        attempt.cancel?.(
+          "The frontend receipt window expired; the effect is unknown. Check status without replaying the command.",
+        )
+        return
+      }
+      timer = setTimeout(wait, Math.min(remaining, 2_147_483_647))
+      timer.unref()
+    }
+    wait()
+    if (!attempt.settle) return promise
+    if (
+      !selected.send({
+        scopeID: caller.scopeID,
+        payload: {
+          type: "server.workbench.request",
+          properties: {
+            requestId: caller.requestId,
+            scopeID: caller.scopeID,
+            sessionID: caller.sessionID,
+            command: input,
+            ...(caller.context && { context: caller.context }),
+          },
+        },
+      })
+    )
+      attempt.cancel?.("The request could not be confirmed as sent; without a frontend receipt the effect is unknown.")
+    return promise
+  }
+}

package/src/presentation/tools/workbench-view.ts

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto"
+import { ScopeContext } from "@ericsanchezok/synergy-harness/scope/context"
+import { Session } from "@ericsanchezok/synergy-harness/session"
+import { Tool } from "@ericsanchezok/synergy-harness/tool/tool"
+import { ResourceReference } from "@ericsanchezok/synergy-util/resource-reference"
+import { FileView } from "@ericsanchezok/synergy-local-runtime/file/view"
+import { WorkbenchView } from "@ericsanchezok/synergy-util/workbench-view"
+import { WorkbenchPresentation } from "../service"
+
+export const WorkbenchViewTool = Tool.define(
+  "workbench_view",
+  {
+    description:
+      "Show an existing note, Workspace file, Browser page or immutable asset in a frontend actively viewing this Session; hide a returned viewId or inspect views. This only presents existing resources: it does not create resources, navigate Browser pages or perform arbitrary UI actions. With multiple eligible frontends, choose a returned clientId. Applied means the frontend confirmed presentation, not that loading content is ready. Waits 30 seconds for a receipt by default; timeout, disconnection or cancellation after dispatch may leave the effect unknown. Use status with the returned requestId to read the retained runtime receipt without replay. Reconnecting and conversation history never replay commands.",
+    parameters: WorkbenchView.Parameters,
+    resourceNeeds(args) {
+      const parsed = WorkbenchView.Parameters.safeParse(args)
+      return {
+        workspace:
+          parsed.success && parsed.data.input.action === "open" && parsed.data.input.target.kind === "workspace-file",
+      }
+    },
+    async execute(parameters, ctx) {
+      const scopeID = ScopeContext.current.scope.id
+      const requestId =
+        ctx.messageID && ctx.callID
+          ? `wvr_${createHash("sha256")
+              .update(JSON.stringify([scopeID, ctx.sessionID, ctx.messageID, ctx.callID]))
+              .digest("hex")}`
+          : `wvr_${crypto.randomUUID()}`
+      let context: ResourceReference.Context | undefined
+      if (parameters.input.action === "open" && parameters.input.target.kind === "workspace-file") {
+        const session = await Session.get(ctx.sessionID)
+        const selected = ctx.resources?.workspace
+        if (
+          session.scope.id === scopeID &&
+          selected?.scopeID === scopeID &&
+          selected.id === session.workspaceID &&
+          (!session.workspace || selected.binding.generation === session.workspace.generation)
+        )
+          context = ResourceReference.capture({
+            id: selected.id,
+            generation: selected.binding.generation,
+            path: ctx.resources?.directory ?? selected.binding.path ?? "",
+          })
+        context ??= { state: "none" }
+        if (context.state === "bound") {
+          const relative = ResourceReference.resolvePath(parameters.input.target.path, context)
+          if (relative)
+            await ctx.ask({
+              permission: "read",
+              patterns: [FileView.resolve(relative, context.workspace.root)],
+              metadata: {},
+            })
+        }
+      }
+      const result = await WorkbenchPresentation.request(parameters, {
+        scopeID,
+        sessionID: ctx.sessionID,
+        requestId,
+        context,
+        signal: ctx.abort,
+      })
+      return { title: `Workbench: ${result.status}`, metadata: { ...result }, output: JSON.stringify(result) }
+    },
+  },
+  {
+    requiresWorkspace: false,
+    exposure: {
+      mode: "search",
+      title: "Workbench view",
+      keywords: ["show", "open", "preview", "note", "file", "asset", "browser", "panel"],
+    },
+  },
+)

package/src/presentation/tools.ts

@@ -0,0 +1,11 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context"
+import { ToolRegistry } from "@ericsanchezok/synergy-harness/tool/registry"
+import { WorkbenchViewTool } from "./tools/workbench-view"
+
+const registered = RuntimeContext.state(() => ({ value: false }))
+
+export function registerPresentationTools() {
+  if (registered().value) return
+  ToolRegistry.registerToolProvider("workbench-presentation", () => [WorkbenchViewTool])
+  registered().value = true
+}