neoctl-web 0.1.0

package/dist/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <path d="M32 4 50 32 32 60 14 32Z" fill="#38bdf8"/>
+</svg>

package/dist/icons.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg">
+  <symbol id="bluesky-icon" viewBox="0 0 16 17">
+    <g clip-path="url(#bluesky-clip)"><path fill="#08060d" d="M7.75 7.735c-.693-1.348-2.58-3.86-4.334-5.097-1.68-1.187-2.32-.981-2.74-.79C.188 2.065.1 2.812.1 3.251s.241 3.602.398 4.13c.52 1.744 2.367 2.333 4.07 2.145-2.495.37-4.71 1.278-1.805 4.512 3.196 3.309 4.38-.71 4.987-2.746.608 2.036 1.307 5.91 4.93 2.746 2.72-2.746.747-4.143-1.747-4.512 1.702.189 3.55-.4 4.07-2.145.156-.528.397-3.691.397-4.13s-.088-1.186-.575-1.406c-.42-.19-1.06-.395-2.741.79-1.755 1.24-3.64 3.752-4.334 5.099"/></g>
+    <defs><clipPath id="bluesky-clip"><path fill="#fff" d="M.1.85h15.3v15.3H.1z"/></clipPath></defs>
+  </symbol>
+  <symbol id="discord-icon" viewBox="0 0 20 19">
+    <path fill="#08060d" d="M16.224 3.768a14.5 14.5 0 0 0-3.67-1.153c-.158.286-.343.67-.47.976a13.5 13.5 0 0 0-4.067 0c-.128-.306-.317-.69-.476-.976A14.4 14.4 0 0 0 3.868 3.77C1.546 7.28.916 10.703 1.231 14.077a14.7 14.7 0 0 0 4.5 2.306q.545-.748.965-1.587a9.5 9.5 0 0 1-1.518-.74q.191-.14.372-.293c2.927 1.369 6.107 1.369 8.999 0q.183.152.372.294-.723.437-1.52.74.418.838.963 1.588a14.6 14.6 0 0 0 4.504-2.308c.37-3.911-.63-7.302-2.644-10.309m-9.13 8.234c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.894 0 1.614.82 1.599 1.82.001 1-.705 1.82-1.6 1.82m5.91 0c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.893 0 1.614.82 1.599 1.82 0 1-.706 1.82-1.6 1.82"/>
+  </symbol>
+  <symbol id="documentation-icon" viewBox="0 0 21 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="m15.5 13.333 1.533 1.322c.645.555.967.833.967 1.178s-.322.623-.967 1.179L15.5 18.333m-3.333-5-1.534 1.322c-.644.555-.966.833-.966 1.178s.322.623.966 1.179l1.534 1.321"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M17.167 10.836v-4.32c0-1.41 0-2.117-.224-2.68-.359-.906-1.118-1.621-2.08-1.96-.599-.21-1.349-.21-2.848-.21-2.623 0-3.935 0-4.983.369-1.684.591-3.013 1.842-3.641 3.428C3 6.449 3 7.684 3 10.154v2.122c0 2.558 0 3.838.706 4.726q.306.383.713.671c.76.536 1.79.64 3.581.66"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M3 10a2.78 2.78 0 0 1 2.778-2.778c.555 0 1.209.097 1.748-.047.48-.129.854-.503.982-.982.145-.54.048-1.194.048-1.749a2.78 2.78 0 0 1 2.777-2.777"/>
+  </symbol>
+  <symbol id="github-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M9.356 1.85C5.05 1.85 1.57 5.356 1.57 9.694a7.84 7.84 0 0 0 5.324 7.44c.387.079.528-.168.528-.376 0-.182-.013-.805-.013-1.454-2.165.467-2.616-.935-2.616-.935-.349-.91-.864-1.143-.864-1.143-.71-.48.051-.48.051-.48.787.051 1.2.805 1.2.805.695 1.194 1.817.857 2.268.649.064-.507.27-.857.49-1.052-1.728-.182-3.545-.857-3.545-3.87 0-.857.31-1.558.8-2.104-.078-.195-.349-1 .077-2.078 0 0 .657-.208 2.14.805a7.5 7.5 0 0 1 1.946-.26c.657 0 1.328.092 1.946.26 1.483-1.013 2.14-.805 2.14-.805.426 1.078.155 1.883.078 2.078.502.546.799 1.247.799 2.104 0 3.013-1.818 3.675-3.558 3.87.284.247.528.714.528 1.454 0 1.052-.012 1.896-.012 2.156 0 .208.142.455.528.377a7.84 7.84 0 0 0 5.324-7.441c.013-4.338-3.48-7.844-7.773-7.844" clip-rule="evenodd"/>
+  </symbol>
+  <symbol id="social-icon" viewBox="0 0 20 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M12.5 6.667a4.167 4.167 0 1 0-8.334 0 4.167 4.167 0 0 0 8.334 0"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M2.5 16.667a5.833 5.833 0 0 1 8.75-5.053m3.837.474.513 1.035c.07.144.257.282.414.309l.93.155c.596.1.736.536.307.965l-.723.73a.64.64 0 0 0-.152.531l.207.903c.164.715-.213.991-.84.618l-.872-.52a.63.63 0 0 0-.577 0l-.872.52c-.624.373-1.003.094-.84-.618l.207-.903a.64.64 0 0 0-.152-.532l-.723-.729c-.426-.43-.289-.864.306-.964l.93-.156a.64.64 0 0 0 .412-.31l.513-1.034c.28-.562.735-.562 1.012 0"/>
+  </symbol>
+  <symbol id="x-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M1.893 1.98c.052.072 1.245 1.769 2.653 3.77l2.892 4.114c.183.261.333.48.333.486s-.068.089-.152.183l-.522.593-.765.867-3.597 4.087c-.375.426-.734.834-.798.905a1 1 0 0 0-.118.148c0 .01.236.017.664.017h.663l.729-.83c.4-.457.796-.906.879-.999a692 692 0 0 0 1.794-2.038c.034-.037.301-.34.594-.675l.551-.624.345-.392a7 7 0 0 1 .34-.374c.006 0 .93 1.306 2.052 2.903l2.084 2.965.045.063h2.275c1.87 0 2.273-.003 2.266-.021-.008-.02-1.098-1.572-3.894-5.547-2.013-2.862-2.28-3.246-2.273-3.266.008-.019.282-.332 2.085-2.38l2-2.274 1.567-1.782c.022-.028-.016-.03-.65-.03h-.674l-.3.342a871 871 0 0 1-1.782 2.025c-.067.075-.405.458-.75.852a100 100 0 0 1-.803.91c-.148.172-.299.344-.99 1.127-.304.343-.32.358-.345.327-.015-.019-.904-1.282-1.976-2.808L6.365 1.85H1.8zm1.782.91 8.078 11.294c.772 1.08 1.413 1.973 1.425 1.984.016.017.241.02 1.05.017l1.03-.004-2.694-3.766L7.796 5.75 5.722 2.852l-1.039-.004-1.039-.004z" clip-rule="evenodd"/>
+  </symbol>
+</svg>

package/dist/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#ffffff" />
+    <script>
+      (() => {
+        try {
+          const saved = localStorage.getItem('neoctl-web.theme')
+          const theme = saved === 'light' || saved === 'dark'
+            ? saved
+            : matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+          document.documentElement.dataset.theme = theme
+          document.documentElement.style.colorScheme = theme
+          document.querySelector('meta[name="theme-color"]').content = theme === 'dark' ? '#0c0c0f' : '#ffffff'
+        } catch {}
+      })()
+    </script>
+    <title>neo runtime</title>
+    <script type="module" crossorigin src="/assets/index-H7num-0s.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BSFq6wfd.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/memory-monitor.mjs

@@ -0,0 +1,150 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import v8 from 'node:v8';
+
+const DEFAULT_SAMPLE_MS = 60_000;
+const DEFAULT_RETENTION_MS = 24 * 60 * 60_000;
+const DEFAULT_PUBLIC_SAMPLES = 60;
+const MAX_PUBLIC_SAMPLES = 60;
+const DEFAULT_MAX_PERSISTED_SAMPLES = 1_440;
+const DEFAULT_MAX_PERSISTED_BYTES = 256 * 1024;
+
+export function createMemoryMonitor({
+  storageFile,
+  sampleMs = DEFAULT_SAMPLE_MS,
+  retentionMs = DEFAULT_RETENTION_MS,
+  publicSamples = DEFAULT_PUBLIC_SAMPLES,
+  maxPersistedSamples = DEFAULT_MAX_PERSISTED_SAMPLES,
+  maxPersistedBytes = DEFAULT_MAX_PERSISTED_BYTES,
+  memoryUsage = () => process.memoryUsage(),
+  heapStatistics = () => v8.getHeapStatistics(),
+  now = () => Date.now(),
+} = {}) {
+  const normalizedSampleMs = positiveInteger(sampleMs, DEFAULT_SAMPLE_MS);
+  const normalizedRetentionMs = Math.max(normalizedSampleMs, positiveInteger(retentionMs, DEFAULT_RETENTION_MS));
+  const persistedSampleLimit = Math.max(2, positiveInteger(maxPersistedSamples, DEFAULT_MAX_PERSISTED_SAMPLES));
+  const persistedByteLimit = Math.max(1_024, positiveInteger(maxPersistedBytes, DEFAULT_MAX_PERSISTED_BYTES));
+  const maxSamples = Math.min(persistedSampleLimit, Math.max(2, Math.ceil(normalizedRetentionMs / normalizedSampleMs) + 1));
+  const publicLimit = Math.min(MAX_PUBLIC_SAMPLES, Math.max(2, positiveInteger(publicSamples, DEFAULT_PUBLIC_SAMPLES)));
+  let samples = [];
+  let timer;
+  let writeQueue = Promise.resolve();
+
+  async function start() {
+    samples = (await readSamples(storageFile, persistedByteLimit)).slice(-maxSamples);
+    await sample();
+    timer = setInterval(() => { void sample(); }, normalizedSampleMs);
+    timer.unref?.();
+  }
+
+  function stop() {
+    if (timer) clearInterval(timer);
+    timer = undefined;
+  }
+
+  async function sample() {
+    const timestamp = now();
+    const usage = memoryUsage();
+    const heap = heapStatistics();
+    const next = {
+      at: new Date(timestamp).toISOString(),
+      rss: byteValue(usage.rss),
+      heapUsed: byteValue(usage.heapUsed),
+      heapTotal: byteValue(usage.heapTotal),
+      heapLimit: byteValue(heap.heap_size_limit),
+      external: byteValue(usage.external),
+      arrayBuffers: byteValue(usage.arrayBuffers),
+    };
+    const cutoff = timestamp - normalizedRetentionMs;
+    samples = [...samples, next]
+      .filter((entry) => Date.parse(entry.at) >= cutoff)
+      .slice(-maxSamples);
+    const persisted = serializePersistedState({
+      version: 1,
+      sampleMs: normalizedSampleMs,
+      retentionMs: normalizedRetentionMs,
+      maxPersistedSamples: maxSamples,
+      maxPersistedBytes: persistedByteLimit,
+      samples,
+    }, persistedByteLimit);
+    samples = persisted.samples;
+    writeQueue = writeQueue
+      .catch(() => undefined)
+      .then(() => writeSamples(storageFile, persisted.text));
+    await writeQueue;
+    return next;
+  }
+
+  function getPublicState() {
+    return {
+      sampleMs: normalizedSampleMs,
+      retentionMs: normalizedRetentionMs,
+      maxPersistedSamples: maxSamples,
+      maxPersistedBytes: persistedByteLimit,
+      current: samples.at(-1) || null,
+      history: samples.slice(-publicLimit),
+    };
+  }
+
+  return { start, stop, sample, getPublicState };
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+
+function byteValue(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.round(number) : 0;
+}
+
+async function readSamples(storageFile, maxBytes) {
+  if (!storageFile) return [];
+  try {
+    const info = await fsp.stat(storageFile);
+    if (info.size > maxBytes) {
+      console.warn(`memory monitor data exceeds ${maxBytes} bytes; resetting history`);
+      return [];
+    }
+    const parsed = JSON.parse(await fsp.readFile(storageFile, 'utf8'));
+    return Array.isArray(parsed?.samples) ? parsed.samples.map(normalizeSample).filter(Boolean) : [];
+  } catch (error) {
+    if (error?.code !== 'ENOENT') console.warn(`failed to read memory monitor data: ${error.message || error}`);
+    return [];
+  }
+}
+
+function normalizeSample(value) {
+  if (!value || typeof value !== 'object' || !Number.isFinite(Date.parse(value.at))) return null;
+  return {
+    at: new Date(Date.parse(value.at)).toISOString(),
+    rss: byteValue(value.rss),
+    heapUsed: byteValue(value.heapUsed),
+    heapTotal: byteValue(value.heapTotal),
+    heapLimit: byteValue(value.heapLimit),
+    external: byteValue(value.external),
+    arrayBuffers: byteValue(value.arrayBuffers),
+  };
+}
+
+function serializePersistedState(value, maxBytes) {
+  let samples = value.samples;
+  let text = `${JSON.stringify({ ...value, samples })}\n`;
+  while (Buffer.byteLength(text, 'utf8') > maxBytes && samples.length > 1) {
+    const excessRatio = maxBytes / Buffer.byteLength(text, 'utf8');
+    const keep = Math.max(1, Math.min(samples.length - 1, Math.floor(samples.length * excessRatio * 0.95)));
+    samples = samples.slice(-keep);
+    text = `${JSON.stringify({ ...value, samples })}\n`;
+  }
+  if (Buffer.byteLength(text, 'utf8') > maxBytes) throw new Error(`memory monitor state exceeds ${maxBytes} bytes`);
+  return { samples, text };
+}
+
+async function writeSamples(storageFile, text) {
+  if (!storageFile) return;
+  await fsp.mkdir(path.dirname(storageFile), { recursive: true });
+  const temporary = `${storageFile}.${process.pid}.tmp`;
+  await fsp.writeFile(temporary, text, 'utf8');
+  await fsp.rename(temporary, storageFile);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "neoctl-web",
+  "version": "0.1.0",
+  "description": "Neo browser workspace with an embedded agent runtime.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "predev": "npm --prefix ../engine run build",
+    "dev": "node scripts/dev.mjs --core local",
+    "dev:package": "node scripts/dev.mjs --core package",
+    "dev:ui": "vite",
+    "test:xhs": "node --test artifacts.test.mjs",
+    "test:runtime": "node --test runtime-router-cleanup.test.mjs runtime-workspaces.test.mjs",
+    "test:plugins": "npm --prefix ../engine run build && node --test plugins.test.mjs plugin-settings.test.mjs tool-settings.test.mjs",
+    "test:monitoring": "node --test cpa-quota.test.mjs memory-monitor.test.mjs",
+    "build": "vite build",
+    "test:cli": "node --test neow.test.mjs",
+    "prestart": "npm run build",
+    "start": "node server.mjs",
+    "preview": "vite preview",
+    "neo": "neo",
+    "neo:web": "neo -web",
+    "neo:login": "neo -login",
+    "neo:help": "neo -help",
+    "prepack": "npm run build && npm run test:cli"
+  },
+  "dependencies": {
+    "@tanstack/vue-virtual": "^3.13.36",
+    "highlight.js": "^11.11.1",
+    "marked": "^18.0.3",
+    "neoctl": "0.2.31",
+    "streaming-markdown": "^0.2.15",
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.4",
+    "vite": "^5.4.21"
+  },
+  "bin": {
+    "neow": "bin/neow.mjs"
+  },
+  "files": [
+    "bin/neow.mjs",
+    "dist",
+    "plugins",
+    "server.mjs",
+    "core-runtime.mjs",
+    "plugins.mjs",
+    "plugin-settings.mjs",
+    "tool-settings.mjs",
+    "runtime-workspaces.mjs",
+    "runtime-router-cleanup.mjs",
+    "cpa-quota.mjs",
+    "memory-monitor.mjs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["neoctl", "agent", "vue", "web"],
+  "license": "Apache-2.0"
+}

package/plugin-settings.mjs

@@ -0,0 +1,67 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+export async function createWebPluginSettings(storageFile) {
+  let state = await readState(storageFile);
+  let writeQueue = Promise.resolve();
+
+  function snapshot() {
+    return structuredClone(state);
+  }
+
+  async function update(next) {
+    state = next;
+    writeQueue = writeQueue.catch(() => undefined).then(() => writeState(storageFile, state));
+    await writeQueue;
+  }
+
+  return {
+    snapshot,
+    globalEnabledIds() {
+      return Array.isArray(state.globalEnabled) ? [...state.globalEnabled] : undefined;
+    },
+    sessionOverrides(sessionId) {
+      const value = state.sessions[String(sessionId || '')];
+      return value && typeof value === 'object' ? { ...value } : {};
+    },
+    async setGlobalEnabled(ids) {
+      await update({ ...state, globalEnabled: [...new Set(ids)].sort() });
+    },
+    async setSessionOverrides(sessionId, overrides) {
+      const id = String(sessionId || '').trim();
+      if (!id) throw new Error('session id is required');
+      const sessions = { ...state.sessions };
+      const normalized = Object.fromEntries(Object.entries(overrides).filter(([, value]) => typeof value === 'boolean'));
+      if (Object.keys(normalized).length) sessions[id] = normalized;
+      else delete sessions[id];
+      await update({ ...state, sessions });
+    },
+  };
+}
+
+async function readState(storageFile) {
+  if (!storageFile) return emptyState();
+  try {
+    const parsed = JSON.parse(await fsp.readFile(storageFile, 'utf8'));
+    return {
+      version: 1,
+      globalEnabled: Array.isArray(parsed?.globalEnabled) ? parsed.globalEnabled.map(String) : undefined,
+      sessions: parsed?.sessions && typeof parsed.sessions === 'object' && !Array.isArray(parsed.sessions) ? parsed.sessions : {},
+    };
+  } catch (error) {
+    if (error?.code !== 'ENOENT') console.warn(`failed to read web plugin settings: ${error.message || error}`);
+    return emptyState();
+  }
+}
+
+function emptyState() {
+  return { version: 1, globalEnabled: undefined, sessions: {} };
+}
+
+async function writeState(storageFile, state) {
+  if (!storageFile) return;
+  await fsp.mkdir(path.dirname(storageFile), { recursive: true });
+  const temporary = `${storageFile}.${process.pid}.tmp`;
+  await fsp.writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  await fsp.rename(temporary, storageFile);
+}

package/plugins/downloads/downloads.mjs

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export class DownloadRegistry {
+  constructor() {
+    this.entries = new Map();
+  }
+
+  add(entry) {
+    const id = crypto.randomUUID();
+    const full = {
+      id,
+      createdAt: Date.now(),
+      ...entry,
+    };
+    this.entries.set(id, full);
+    return full;
+  }
+
+  get(id) {
+    const entry = this.entries.get(String(id || ''));
+    if (!entry) return undefined;
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.entries.delete(entry.id);
+      return undefined;
+    }
+    return entry;
+  }
+}
+
+export function createExposeDownloadsTool(options) {
+  const ttlMs = options.ttlMs ?? 30 * 60 * 1000;
+
+  return {
+    name: 'expose_downloads',
+    description:
+      'Expose one or more existing local files for the web user to download. Input must be absolute file paths. The result follows neoctl.resource-link.v1: copy each downloads[].markdown value verbatim into the final response, without rewriting or prefixing its link.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Absolute file paths to expose for browser download.',
+        },
+      },
+      required: ['paths'],
+      additionalProperties: false,
+    },
+    metadata: {
+      readOnly: true,
+      concurrent: true,
+      visible: true,
+      requiresApproval: false,
+      maxResultSizeChars: 12000,
+    },
+    validate(input) {
+      const paths = Array.isArray(input?.paths)
+        ? input.paths.map((item) => String(item || '').trim()).filter(Boolean)
+        : [];
+      if (!paths.length) throw new Error('paths must be a non-empty array');
+      if (paths.length > 20) throw new Error('too many paths; maximum is 20');
+      for (const filePath of paths) {
+        if (!path.isAbsolute(filePath)) throw new Error(`path must be absolute: ${filePath}`);
+      }
+      return { paths };
+    },
+    async execute(input, context) {
+      const downloads = [];
+      for (const rawPath of input.paths) {
+        const absolutePath = path.resolve(rawPath);
+        const stat = await fsp.stat(absolutePath).catch(() => undefined);
+        if (!stat) throw new Error(`file does not exist: ${absolutePath}`);
+        if (!stat.isFile()) throw new Error(`path is not a file: ${absolutePath}`);
+        const entry = options.registry.add({
+          absolutePath,
+          filename: path.basename(absolutePath),
+          sizeBytes: stat.size,
+          expiresAt: Date.now() + ttlMs,
+          sessionId: context.session?.sessionId,
+        });
+        const url = `/api/downloads/${encodeURIComponent(entry.id)}`;
+        const reference = `sandbox:${url}`;
+        downloads.push({
+          id: entry.id,
+          filename: entry.filename,
+          sizeBytes: entry.sizeBytes,
+          url,
+          reference,
+          markdown: `[${entry.filename.replace(/([\\\]])/g, '\\$1')}](${reference})`,
+          expiresAt: new Date(entry.expiresAt).toISOString(),
+          expiresAtEpochMs: entry.expiresAt,
+        });
+      }
+      await options.onExpose?.({ sessionId: context.session?.sessionId, downloads });
+      return {
+        ok: true,
+        output: {
+          resourceProtocol: 'neoctl.resource-link.v1',
+          usage: 'Copy downloads[].markdown verbatim when linking the resource. Do not alter the reference URI.',
+          downloads,
+          _ui: {
+            resources: downloads.map((item) => ({
+              kind: 'download',
+              url: item.url,
+              reference: item.reference,
+              label: item.filename,
+              downloadName: item.filename,
+              sizeBytes: item.sizeBytes,
+              expiresAt: item.expiresAtEpochMs,
+            })),
+          },
+        },
+        summary: `Exposed ${downloads.length} file(s) for browser download.`,
+      };
+    },
+  };
+}
+
+export function serveDownload(registry, req, res, id) {
+  const entry = registry.get(id);
+  if (!entry) {
+    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify({ error: 'download not found or expired' }));
+    return;
+  }
+
+  res.writeHead(200, {
+    'Content-Type': 'application/octet-stream',
+    'Content-Length': String(entry.sizeBytes),
+    'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(entry.filename)}`,
+    'Cache-Control': 'no-store',
+  });
+
+  fs.createReadStream(entry.absolutePath)
+    .on('error', () => {
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('failed to read file');
+      } else {
+        res.destroy();
+      }
+    })
+    .pipe(res);
+}

package/plugins/downloads/index.mjs

@@ -0,0 +1,19 @@
+import { createExposeDownloadsTool, DownloadRegistry, serveDownload } from './downloads.mjs';
+
+export function createPlugin() {
+  const registry = new DownloadRegistry();
+  return {
+    tools: [createExposeDownloadsTool({ registry })],
+    promptSections: [{
+      name: 'Web Downloads',
+      cacheStable: true,
+      content: 'When you create, modify, export, package, or identify local files that the web user should receive, call expose_downloads with the relevant absolute paths before the final response. For every link in your response, copy the returned downloads[].markdown value verbatim. This is the neoctl.resource-link.v1 protocol: never construct a link, alter the reference URI, or add/remove a sandbox: prefix. The tool also returns expiresAt as an ISO timestamp.',
+    }],
+    async route(req, res, url) {
+      if (req.method !== 'GET' || !url.pathname.startsWith('/api/downloads/')) return false;
+      const id = decodeURIComponent(url.pathname.slice('/api/downloads/'.length));
+      await serveDownload(registry, req, res, id);
+      return true;
+    },
+  };
+}

package/plugins/downloads/neo-plugin.json

@@ -0,0 +1,9 @@
+{
+  "protocol": "neo-plugin/v1",
+  "id": "downloads",
+  "name": "文件下载",
+  "version": "1.0.0",
+  "entry": "index.mjs",
+  "defaultEnabled": true,
+  "description": "将本地文件安全地暴露为临时浏览器下载链接。"
+}