dsh-edge 0.1.0

package/src/sse.ts

@@ -0,0 +1,86 @@
+/** Server-sent-event encoding for canonical DSH SessionEvents. */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+
+const encoder = new TextEncoder()
+const MAX_LIVE_STREAM_QUEUED_BYTES = 1_048_576
+
+/** Encode one upstream event without translating its envelope or payload. */
+export function encodeSessionEvent(event: SessionEvent): Uint8Array {
+  const eventType = encodeEventType(event.type)
+  return encoder.encode(
+    `id: ${event.seq}\nevent: ${eventType}\ndata: ${JSON.stringify(event)}\n\n`,
+  )
+}
+
+/** Keep canonical names stable while making arbitrary ignorable names one SSE field. */
+function encodeEventType(type: string): string {
+  return type
+    .replaceAll('%', '%25')
+    .replaceAll('\r', '%0D')
+    .replaceAll('\n', '%0A')
+}
+
+/** Headers used by live and finite replay streams. */
+export function edgeEventStreamHeaders(extra: HeadersInit = {}): Headers {
+  const headers = new Headers(extra)
+  headers.set('cache-control', 'no-cache, no-transform')
+  headers.set('content-type', 'text/event-stream; charset=utf-8')
+  headers.set('x-accel-buffering', 'no')
+  return headers
+}
+
+export interface LiveSessionEventStream {
+  readonly stream: ReadableStream<Uint8Array>
+  /** Settles after the producer closes or errors the client-visible stream. */
+  readonly completion: Promise<void>
+}
+
+/** Run an event producer whose escaped failures become client-visible stream errors. */
+export function createLiveSessionEventStream(
+  run: (publish: (event: SessionEvent) => void) => Promise<void>,
+  onFailure: (error: unknown) => void,
+): LiveSessionEventStream {
+  let connected = true
+  let settle!: () => void
+  const completion = new Promise<void>((resolve) => { settle = resolve })
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      void Promise.resolve().then(async () => run((event) => {
+        if (!connected) return
+        try {
+          const chunk = encodeSessionEvent(event)
+          if (controller.desiredSize === null || controller.desiredSize < chunk.byteLength) {
+            connected = false
+            controller.error(new Error('dsh-edge event stream client is too slow.'))
+            return
+          }
+          controller.enqueue(chunk)
+        } catch {
+          connected = false
+        }
+      })).then(() => {
+        if (connected) {
+          try {
+            controller.close()
+          } catch {
+            connected = false
+          }
+        }
+      }, (error: unknown) => {
+        onFailure(error)
+        if (connected) {
+          connected = false
+          controller.error(new Error('dsh-edge turn transport failed.'))
+        }
+      }).finally(settle)
+    },
+    cancel() {
+      connected = false
+    },
+  }, {
+    highWaterMark: MAX_LIVE_STREAM_QUEUED_BYTES,
+    size: chunk => chunk.byteLength,
+  })
+  return { stream, completion }
+}

package/src/web-search.ts

@@ -0,0 +1,38 @@
+/** Upstream DeepSeek Web Search composition for the Cloudflare runtime. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import * as TimeoutPolicy from '@deepseek-ai/dsh-tool-call-timeout-policy'
+import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
+import WebRuntime from '@deepseek-ai/dsh-web'
+import * as DeepSeekWebSearch from '@deepseek-ai/dsh-web-search-deepseek'
+
+/** Validate the credential-bearing Anthropic-compatible search endpoint. */
+export function resolveEdgeSearchBaseURL(raw?: string): string {
+  const value = raw ?? DeepSeekWebSearch.DEEPSEEK_DEFAULT_BASE_URL
+  let parsed: URL
+  try {
+    parsed = new URL(value)
+  } catch {
+    throw new Error('DEEPSEEK_SEARCH_BASE_URL must be a valid HTTP(S) URL.')
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error('DEEPSEEK_SEARCH_BASE_URL must be a valid HTTP(S) URL.')
+  }
+  if (parsed.username.length > 0 || parsed.password.length > 0) {
+    throw new Error('DEEPSEEK_SEARCH_BASE_URL must be an HTTP(S) URL without credentials.')
+  }
+  if (parsed.search.length > 0 || parsed.hash.length > 0) {
+    throw new Error('DEEPSEEK_SEARCH_BASE_URL must not contain a query or fragment.')
+  }
+  return parsed.href.replace(/\/+$/u, '')
+}
+
+/** Mount the shipped upstream search seam, provider, and search-only model tool. */
+export async function installEdgeWebSearch(ctx: Context, rawBaseURL?: string): Promise<void> {
+  await ctx.plugin(WebRuntime, { searchProvider: DeepSeekWebSearch.DEEPSEEK_PROVIDER_ID })
+  await ctx.plugin(DeepSeekWebSearch, {
+    baseURL: resolveEdgeSearchBaseURL(rawBaseURL),
+  })
+  await ctx.plugin(TimeoutPolicy)
+  await ctx.plugin(ToolWeb, { search: true, fetch: false })
+}

package/src/workspace.ts

@@ -0,0 +1,270 @@
+/** Validation and execution helpers for the Cloudflare Computer workspace. */
+
+import { getWorkspace } from '@cloudflare/computer'
+import type { EdgeShellResult } from './agent.ts'
+import {
+  DIRECT_SHELL_OUTPUT_TRUNCATED,
+  EDGE_SHELL_OUTPUT_LIMIT_BYTES,
+} from './direct-shell-protocol.ts'
+import { EdgeExecutionId } from './protocol.ts'
+
+const MAX_COMMAND_BYTES = 16_384
+const DEFAULT_COMMAND_TIMEOUT_MS = 120_000
+const DEFAULT_MAX_COMMAND_TIMEOUT_MS = 120_000
+const MAX_TIMER_DELAY_MS = 2_147_483_647
+const textEncoder = new TextEncoder()
+
+export const MAX_TEXT_FILE_BYTES = 1_048_576
+
+/** Invalid workspace input reported to an HTTP caller. */
+export class EdgeWorkspaceRequestError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message)
+  }
+}
+
+/** Cloudflare Computer client returned by the workspace binding. */
+export type EdgeWorkspace = Awaited<ReturnType<typeof getWorkspace>>
+
+/** Validated deployment policy applied to every Computer shell execution. */
+export interface EdgeCommandTimeoutPolicy {
+  defaultTimeoutMs: number
+  maxTimeoutMs: number
+}
+
+/** Resolve the default and caller-selectable ceiling for Computer commands. */
+export function resolveEdgeCommandTimeoutPolicy(
+  defaultRaw?: string,
+  maxRaw?: string,
+): EdgeCommandTimeoutPolicy {
+  const maxTimeoutMs = resolveDeploymentTimeout(
+    maxRaw,
+    DEFAULT_MAX_COMMAND_TIMEOUT_MS,
+    'DSH_EDGE_MAX_COMMAND_TIMEOUT_MS',
+  )
+  const defaultTimeoutMs = resolveDeploymentTimeout(
+    defaultRaw,
+    DEFAULT_COMMAND_TIMEOUT_MS,
+    'DSH_EDGE_DEFAULT_COMMAND_TIMEOUT_MS',
+  )
+  if (defaultTimeoutMs > maxTimeoutMs) {
+    throw new Error(
+      'dsh-edge: DSH_EDGE_DEFAULT_COMMAND_TIMEOUT_MS must be no greater than '
+      + 'DSH_EDGE_MAX_COMMAND_TIMEOUT_MS',
+    )
+  }
+  return { defaultTimeoutMs, maxTimeoutMs }
+}
+
+interface EdgeWorkspaceFiles {
+  stat(path: string): Promise<{ size: number }>
+  readFile(path: string): Promise<ReadableStream<Uint8Array>>
+}
+
+/** Refuse an oversized VFS entry before and while consuming its opened byte stream. */
+export async function readBoundedWorkspaceFile(
+  files: EdgeWorkspaceFiles,
+  path: string,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const entry = await files.stat(path)
+  if (entry.size > MAX_TEXT_FILE_BYTES) {
+    throw new EdgeWorkspaceRequestError(413, 'Text files are limited to 1 MiB in the prototype API.')
+  }
+  const stream = await files.readFile(path)
+  const reader = stream.getReader()
+  const chunks: Uint8Array[] = []
+  let byteLength = 0
+  try {
+    while (true) {
+      const next = await reader.read()
+      if (next.done) break
+      byteLength += next.value.byteLength
+      if (byteLength > MAX_TEXT_FILE_BYTES) {
+        chunks.length = 0
+        await reader.cancel().catch(() => undefined)
+        throw new EdgeWorkspaceRequestError(
+          413,
+          'Text files are limited to 1 MiB in the prototype API.',
+        )
+      }
+      chunks.push(next.value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  const contents = new Uint8Array(byteLength)
+  let offset = 0
+  for (const chunk of chunks) {
+    contents.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return contents
+}
+
+/** Validate an absolute path inside the persistent workspace root. */
+export function requireWorkspacePath(value: unknown): string {
+  if (
+    typeof value !== 'string'
+    || (value !== '/workspace' && !value.startsWith('/workspace/'))
+  ) {
+    throw new EdgeWorkspaceRequestError(400, 'A path below /workspace/ is required.')
+  }
+  if (value.includes('\0') || value.split('/').includes('..')) {
+    throw new EdgeWorkspaceRequestError(
+      400,
+      'Workspace paths cannot contain NUL bytes or parent traversal.',
+    )
+  }
+  return value
+}
+
+/** Validate a just-bash command accepted from HTTP or a model tool call. */
+export function requireCommand(value: unknown): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new EdgeWorkspaceRequestError(400, 'A non-empty command is required.')
+  }
+  if (textEncoder.encode(value).byteLength > MAX_COMMAND_BYTES) {
+    throw new EdgeWorkspaceRequestError(413, 'Commands are limited to 16 KiB.')
+  }
+  return value
+}
+
+/** Execute one bounded just-bash command and normalize its result. */
+export async function executeWorkspaceCommand(
+  workspace: EdgeWorkspace,
+  command: string,
+  cwd: string,
+  timeoutPolicy: EdgeCommandTimeoutPolicy,
+  timeoutMs?: number,
+  signal?: AbortSignal,
+): Promise<EdgeShellResult> {
+  const effectiveTimeoutMs = timeoutMs ?? timeoutPolicy.defaultTimeoutMs
+  if (!Number.isInteger(effectiveTimeoutMs)
+    || effectiveTimeoutMs <= 0
+    || effectiveTimeoutMs > timeoutPolicy.maxTimeoutMs) {
+    throw new EdgeWorkspaceRequestError(
+      400,
+      `timeoutMs must be a positive integer no greater than ${timeoutPolicy.maxTimeoutMs}.`,
+    )
+  }
+  signal?.throwIfAborted()
+  await workspace.fs.mkdir('/workspace', { recursive: true })
+  signal?.throwIfAborted()
+  const deadline = commandDeadline(effectiveTimeoutMs)
+  using execution = await workspace.runtime.exec(command, {
+    cwd,
+    timeoutMs: effectiveTimeoutMs,
+  })
+  let interruptionRequested = false
+  const interrupt = (): Promise<void> => {
+    interruptionRequested = true
+    return execution.kill('SIGINT').catch(() => undefined)
+  }
+  const abort = (): void => {
+    void interrupt()
+  }
+  signal?.addEventListener('abort', abort, { once: true })
+  if (signal?.aborted === true) abort()
+  const stdout: Uint8Array[] = []
+  const stderr: Uint8Array[] = []
+  let retainedBytes = 0
+  let outputTruncated = false
+  let exitCode = -1
+  const reader = execution.getReader()
+  try {
+    while (true) {
+      const next = await reader.read()
+      if (next.done) break
+      const event = next.value
+      if (event.name === 'exit') {
+        deadline.complete()
+        exitCode = event.code
+        if (event.result === DIRECT_SHELL_OUTPUT_TRUNCATED) {
+          outputTruncated = true
+          interruptionRequested = true
+        }
+        continue
+      }
+
+      const remaining = EDGE_SHELL_OUTPUT_LIMIT_BYTES - retainedBytes
+      if (remaining > 0) {
+        // Copy rather than retain a subarray view: an oversized event may use
+        // a much larger backing buffer that must become collectible here.
+        const retained = event.value.slice(0, remaining)
+        if (event.name === 'stdout') stdout.push(retained)
+        else stderr.push(retained)
+        retainedBytes += retained.byteLength
+      }
+      if (event.value.byteLength > remaining && !outputTruncated) {
+        outputTruncated = true
+        await interrupt()
+      }
+    }
+  } finally {
+    reader.releaseLock()
+    signal?.removeEventListener('abort', abort)
+  }
+  return {
+    executionId: EdgeExecutionId(execution.id),
+    status: executionStatus(exitCode, interruptionRequested),
+    timedOut: deadline.timedOut,
+    exitCode,
+    stdout: decodeChunks(stdout),
+    stderr: decodeChunks(stderr),
+    outputTruncated,
+  }
+}
+
+function commandDeadline(timeoutMs: number): { complete(): void; readonly timedOut: boolean } {
+  const expiresAt = performance.now() + timeoutMs
+  let completedAt: number | undefined
+  return {
+    complete() { completedAt ??= performance.now() },
+    get timedOut() { return (completedAt ?? performance.now()) >= expiresAt },
+  }
+}
+
+function executionStatus(
+  exitCode: number,
+  interruptionRequested: boolean,
+): EdgeShellResult['status'] {
+  if (interruptionRequested) return 'cancelled'
+  if (exitCode === 0) return 'completed'
+  return 'failed'
+}
+
+function resolveDeploymentTimeout(raw: string | undefined, fallback: number, name: string): number {
+  if (raw === undefined) return fallback
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`dsh-edge: ${name} must be a positive integer`)
+  }
+  if (value > MAX_TIMER_DELAY_MS) {
+    throw new Error(`dsh-edge: ${name} must be no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+  return value
+}
+
+function decodeChunks(chunks: Uint8Array[]): string {
+  const byteLength = chunks.reduce((total, chunk) => total + chunk.byteLength, 0)
+  const output = new Uint8Array(byteLength)
+  let offset = 0
+  for (const chunk of chunks) {
+    output.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  // A byte-exact cut can land inside one UTF-8 code point. The shell backend
+  // encoded these bytes from strings, so at most the final three bytes need
+  // dropping to retain a valid prefix without introducing U+FFFD expansion.
+  for (let dropped = 0; dropped <= 3 && dropped <= output.byteLength; dropped += 1) {
+    try {
+      return new TextDecoder('utf-8', { fatal: true }).decode(
+        output.subarray(0, output.byteLength - dropped),
+      )
+    } catch {
+      // Try the preceding UTF-8 boundary.
+    }
+  }
+  throw new Error('dsh-edge: shell output was not valid UTF-8')
+}

package/wrangler.jsonc

@@ -0,0 +1,56 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "dsh-edge",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-08-14",
+  "compatibility_flags": [
+    "nodejs_compat"
+  ],
+  "minify": true,
+  "assets": {
+    "binding": "ASSETS",
+    "directory": "./dist",
+    "not_found_handling": "single-page-application",
+    "run_worker_first": [
+      "/api/*",
+      "/",
+      "/login"
+    ]
+  },
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "DSH_EDGE_INSTANCE",
+        "class_name": "DshEdgeInstance"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": [
+        "DshEdgeInstance"
+      ]
+    }
+  ],
+  "observability": {
+    "enabled": true
+  },
+  "env": {
+    "isolated": {
+      "durable_objects": {
+        "bindings": [
+          {
+            "name": "DSH_EDGE_INSTANCE",
+            "class_name": "DshEdgeInstance"
+          }
+        ]
+      },
+      "worker_loaders": [
+        {
+          "binding": "LOADER"
+        }
+      ]
+    }
+  }
+}