@rosmeowtis/dsh-aria2-rpc 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-aria2-rpc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @rosmeowtis/dsh-aria2-rpc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 插件：连接**已有的 aria2 JSON-RPC 服务**（HTTP，`/jsonrpc`），为模型提供四个工具。不携带、不启动、不管理 aria2。
+
+| 工具 | 作用 |
+| --- | --- |
+| `aria2_download` | 提交单文件直链下载，立即返回 GID；可选保存目录、文件名、来源提供的校验和（sha-256 / sha-1 / md5，实际计算由 aria2 执行）、任务级 HTTP 代理。 |
+| `aria2_status` | 读取任务状态、进度、速度、文件路径与脱敏错误。 |
+| `aria2_list` | 列出 active / waiting / stopped 或全部任务；只读，支持 limit/offset。 |
+| `aria2_control` | `pause` / `resume` / `cancel`。取消保留部分文件，不关闭 aria2。 |
+
+> 工具定义的上下文占用： ~400 token。
+
+配置：设置 → 插件 → Aria2 RPC，可设置 `rpcHost`、`rpcPort`、密钥与请求超时；密钥固定使用凭据 `ARIA2_RPC_SECRET`，无密钥时不发送；HTTP 不加密，远程连接请仅在可信网络或加密隧道中使用。
+
+设置页的「测试连接」使用当前输入的主机、端口与超时调用 `aria2.getVersion`，无需先保存。密钥框中有内容时使用该临时值，否则从当前凭据引用读取；测试不保存配置、不创建任务，成功显示 aria2 版本，失败显示连通性、超时或鉴权提示。
+
+下载完成或失败时，插件通过 aria2 的 WebSocket 通知向发起会话推送一条消息。只跟踪本进程内由 `aria2_download` 创建的任务；插件重载后，重载前创建的任务不再推送。
+
+创建与控制仅在退出计划模式后的完全访问模式执行；状态读取不受此限。结果未知的修改请求会返回可查询的 GID，不会自动重复提交。
+
+## 开发
+
+```sh
+npm install
+npm test   # 构建 + 语法检查 + 模拟 RPC 单元测试（不真实下载）
+```
+
+安装到当前 profile：DSH 的插件管理 `install_bundle`，target 为本目录绝对路径。

package/client.js

@@ -0,0 +1,192 @@
+window.__ModuleLoader__.load({
+  id: '@rosmeowtis/dsh-aria2-rpc',
+  factory(require) {
+    const React = require('react');
+    const h = React.createElement;
+    const NS = 'aria2-rpc';
+    const dictionaries = {
+      zh: {
+        host: 'RPC 主机', port: 'RPC 端口', timeout: '请求超时（毫秒）',
+        hostHint: '当前使用 HTTP，请确保在可信网络下使用。',
+        save: '保存连接设置', saving: '保存中…', saved: '连接设置已保存。',
+        rejected: '保存失败或配置已在别处变更。草稿已保留；请重新打开页面核对后再保存。',
+        readOnly: '配置不可用或当前连接不允许写入。',
+        secret: 'RPC 密钥', configured: '已配置', missing: '未配置', unknown: '状态未知',
+        secretHint: '仅写入 DSH 凭据存储，不回显原值；留空不改变。清除存储值后，环境变量等来源仍可能生效。',
+        saveSecret: '保存密钥', clearSecret: '清除存储的密钥', secretSaved: '密钥操作已完成。',
+        secretFailed: '凭据操作失败，请检查连接权限；已保存的设置不受影响。',
+        details: '连接现有 aria2 RPC 服务，不自带 aria2，提供创建、查询、暂停、恢复、取消功能。',
+        test: '测试连接', testing: '测试中…', connected: '连接成功，aria2 版本：',
+        testFailed: '测试失败：', NETWORK: '无法连接，请检查主机、端口及防火墙。', TIMEOUT: '请求超时。',
+        RPC_ERROR: 'RPC 拒绝请求，请检查密钥及服务配置。', HTTP_ERROR: 'HTTP 响应异常，请检查 RPC 端口。',
+        INVALID_INPUT: '主机、端口或超时格式不正确。', BAD_RESPONSE: '响应不是有效的 aria2 RPC 版本信息。',
+        REDIRECT: 'RPC 地址发生重定向，已拒绝。', RESPONSE_TOO_LARGE: 'RPC 响应过大。', ABORTED: '测试已取消。',
+        CREDENTIAL_ERROR: '无法读取凭据。', TRANSPORT_ERROR: '无法调用 DSH 测试接口，请刷新页面重试。',
+      },
+      en: {
+        host: 'RPC host', port: 'RPC port', timeout: 'Request timeout (ms)',
+        hostHint: 'Uses HTTP; use it only on a trusted network.',
+        save: 'Save connection settings', saving: 'Saving…', saved: 'Connection settings saved.',
+        rejected: 'Save failed or settings changed elsewhere. Your draft was kept; reopen this page to review before saving again.',
+        readOnly: 'Settings are unavailable or this connection is read-only.',
+        secret: 'RPC secret', configured: 'Configured', missing: 'Not configured', unknown: 'Unknown',
+        secretHint: 'Written only to DSH credentials, never read back. Blank keeps it unchanged. Environment values may still apply after removing the stored secret.',
+        saveSecret: 'Save secret', clearSecret: 'Remove stored secret', secretSaved: 'Credential operation completed.',
+        secretFailed: 'Credential operation failed. Check connection permissions; saved settings are unaffected.',
+        details: 'Connects to an existing aria2 RPC service without bundling aria2; provides create, query, pause, resume, and cancel.',
+        test: 'Test connection', testing: 'Testing…', connected: 'Connected, aria2 version: ',
+        testFailed: 'Connection test failed: ', NETWORK: 'Cannot connect. Check host, port and firewall.', TIMEOUT: 'Request timed out.',
+        RPC_ERROR: 'RPC rejected the request. Check the secret and service configuration.', HTTP_ERROR: 'Unexpected HTTP response. Check the RPC port.',
+        INVALID_INPUT: 'Invalid host, port or timeout.', BAD_RESPONSE: 'Not a valid aria2 RPC version response.',
+        REDIRECT: 'RPC redirect rejected.', RESPONSE_TOO_LARGE: 'RPC response is too large.', ABORTED: 'Test cancelled.',
+        CREDENTIAL_ERROR: 'Cannot read the credential.', TRANSPORT_ERROR: 'Cannot call the DSH test endpoint. Refresh and retry.',
+      },
+    };
+    const css = `
+      .aria2-rpc-form{display:flex;flex-direction:column;gap:16px;color:var(--dsw-alias-label-primary);font-size:14px;line-height:1.6;max-width:680px;overflow-wrap:anywhere}
+      .aria2-rpc-form label{display:flex;flex-direction:column;gap:8px;font-weight:500}
+      .aria2-rpc-form input{box-sizing:border-box;width:100%;min-height:40px;padding:8px 12px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;font-weight:400}
+      .aria2-rpc-form input:focus-visible,.aria2-rpc-form button:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}
+      .aria2-rpc-form input::placeholder{color:var(--dsw-alias-state-idle-primary);opacity:1}
+      .aria2-rpc-form p{margin:0;color:var(--dsw-alias-label-secondary);font-weight:400}
+      .aria2-rpc-form .aria2-rpc-pair{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+      .aria2-rpc-form button{min-height:40px;padding:8px 14px;border-radius:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);font:inherit;cursor:pointer}
+      .aria2-rpc-form button:hover:not(:disabled){background:var(--dsw-alias-bg-layer-1)}
+      .aria2-rpc-form button:disabled,.aria2-rpc-form input:disabled{opacity:.5;cursor:default}
+      .aria2-rpc-form .aria2-rpc-actions{display:flex;flex-wrap:wrap;gap:8px;align-items:center}
+      .aria2-rpc-form .aria2-rpc-error{color:var(--dsw-alias-state-error-primary)}
+      .aria2-rpc-form .aria2-rpc-note{background:var(--dsw-alias-bg-layer-2);border-radius:8px;padding:10px 12px;font-size:13px}
+      .aria2-rpc-form .aria2-rpc-secret-head{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+      .aria2-rpc-form .aria2-rpc-secret-head label{display:block;font-weight:500}
+      .aria2-rpc-form .aria2-rpc-status{display:inline-flex;align-items:center;padding:2px 8px;border-radius:999px;font-size:12px;font-weight:500;line-height:1.5}
+      .aria2-rpc-form .aria2-rpc-status.configured{background:#15803d;color:#fff}
+      .aria2-rpc-form .aria2-rpc-status.missing{background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-secondary)}
+      .aria2-rpc-form .aria2-rpc-test.success{background:#15803d;border-color:#15803d;color:#fff}
+      .aria2-rpc-form .aria2-rpc-test.failure{background:#b91c1c;border-color:#b91c1c;color:#fff}
+      .aria2-rpc-form .aria2-rpc-test.success:hover:not(:disabled){background:#116932}
+      .aria2-rpc-form .aria2-rpc-test.failure:hover:not(:disabled){background:#991b1b}
+      .aria2-rpc-form fieldset{margin:0;padding:16px 0 0;border:0;border-top:1px solid var(--dsw-alias-border-l1);display:flex;flex-direction:column;gap:12px;min-width:0}
+      @media(max-width:520px){.aria2-rpc-form .aria2-rpc-pair{grid-template-columns:1fr}}
+    `;
+    return {
+      inject: ['slots', 'locale', 'remote', 'remote.credentials'],
+      apply(ctx) {
+        for (const [lang, dictionary] of Object.entries(dictionaries)) ctx.effect(() => ctx.locale.register(NS, lang, dictionary));
+        const t = ctx.locale.bind(NS);
+        ctx.inject(['configForms'], ready => {
+          const form = ready.configForms.get('aria2-rpc');
+          function Settings() {
+            React.useSyncExternalStore(fn => ctx.locale.subscribe(fn), () => ctx.locale.getSnapshot());
+            const state = React.useSyncExternalStore(fn => form.subscribe(fn), () => form.getSnapshot());
+            const [draft, setDraft] = React.useState(null);
+            const [busy, setBusy] = React.useState(false);
+            const [testing, setTesting] = React.useState(false);
+            const [testState, setTestState] = React.useState('idle');
+            const testAbort = React.useRef(null);
+            React.useEffect(() => () => testAbort.current?.abort(), []);
+            const [notice, setNotice] = React.useState('');
+            const [failed, setFailed] = React.useState(false);
+            const [secret, setSecret] = React.useState('');
+            const [credential, setCredential] = React.useState(null);
+            const values = state.value || {};
+            const ref = values.rpcSecretRef || 'ARIA2_RPC_SECRET';
+            const writable = state.status === 'ready' && state.writable;
+            const disabled = busy || !writable;
+            const remote = () => ctx.remote.credentials;
+            const refreshCredential = async () => {
+              const result = await remote().describe([ref]);
+              if (!result.ok) throw new Error('credential unavailable');
+              return result.value[ref];
+            };
+            React.useEffect(() => {
+              let active = true;
+              setCredential(null);
+              setSecret('');
+              refreshCredential().then(value => { if (active) setCredential(value); }).catch(() => {});
+              return () => { active = false; };
+            }, [ref]);
+            const edit = (key, value) => {
+              setDraft(old => ({ revision: old ? old.revision : state.revision, values: { ...(old ? old.values : {}), [key]: value } }));
+              setNotice(''); setTestState('idle');
+            };
+            const save = async event => {
+              event.preventDefault();
+              if (!draft) return;
+              setBusy(true); setNotice(''); setFailed(false);
+              try {
+                const ops = Object.entries(draft.values).map(([key, value]) => ({ op: 'set', path: [key], value: key === 'rpcPort' || key === 'rpcTimeoutMs' ? Number(value) : value }));
+                if (!await form.mutate(ops, draft.revision)) throw new Error('settings refused');
+                setDraft(null); setNotice(t('saved'));
+              } catch { setFailed(true); setNotice(t('rejected')); }
+              finally { setBusy(false); }
+            };
+            const writeSecret = async clear => {
+              setBusy(true); setNotice(''); setFailed(false);
+              try {
+                const result = clear ? await remote().unset(ref) : await remote().set(ref, secret);
+                if (!result.ok) throw new Error('credential refused');
+                setSecret('');
+                setCredential(await refreshCredential());
+                setNotice(t('secretSaved'));
+              } catch { setFailed(true); setNotice(t('secretFailed')); }
+              finally { setBusy(false); }
+            };
+            const testConnection = async () => {
+              const current = { ...values, ...(draft ? draft.values : {}) };
+              const controller = new AbortController();
+              testAbort.current = controller;
+              setTesting(true); setTestState('testing'); setBusy(true); setNotice(''); setFailed(false);
+              try {
+                const response = await fetch('./api/aria2-rpc.test', {
+                  method: 'POST', credentials: 'same-origin', headers: { 'content-type': 'application/json' },
+                  signal: controller.signal,
+                  body: JSON.stringify({ rpcHost: current.rpcHost, rpcPort: Number(current.rpcPort), rpcTimeoutMs: Number(current.rpcTimeoutMs), rpcSecretRef: current.rpcSecretRef, ...(secret ? { secret } : {}) }),
+                });
+                const result = await response.json();
+                if (controller.signal.aborted) return;
+                if (response.ok && result.ok === true && typeof result.version === 'string') { setTestState('success'); setNotice(t('connected') + result.version); }
+                else {
+                  const code = ['NETWORK', 'TIMEOUT', 'RPC_ERROR', 'HTTP_ERROR', 'INVALID_INPUT', 'BAD_RESPONSE', 'REDIRECT', 'RESPONSE_TOO_LARGE', 'ABORTED', 'CREDENTIAL_ERROR'].includes(result.code) ? result.code : 'TRANSPORT_ERROR';
+                  setTestState('failure'); setFailed(true); setNotice(t('testFailed') + t(code));
+                }
+              } catch {
+                if (!controller.signal.aborted) { setTestState('failure'); setFailed(true); setNotice(t('testFailed') + t('TRANSPORT_ERROR')); }
+              } finally {
+                if (!controller.signal.aborted) { setTesting(false); setBusy(false); }
+              }
+            };
+            const placeholders = { rpcHost: '127.0.0.1', rpcPort: '6800', rpcTimeoutMs: '10000' };
+            const field = (key, label, fallback, type, props = {}) => h('label', { key, htmlFor: `aria2-${key}` }, t(label), h('input', {
+              id: `aria2-${key}`, type, placeholder: placeholders[key], value: draft && key in draft.values ? draft.values[key] : values[key] ?? fallback,
+              disabled, onChange: e => edit(key, e.target.value), required: true, spellCheck: false, ...props,
+            }));
+            return h('div', { className: 'aria2-rpc-form' },
+              h('style', null, css),
+              h('p', { className: 'aria2-rpc-note' }, t('details')),
+              !writable && h('p', { role: 'status' }, t('readOnly')),
+              h('form', { onSubmit: save, className: 'aria2-rpc-form' },
+                field('rpcHost', 'host', '127.0.0.1', 'text', { pattern: '[A-Za-z0-9][A-Za-z0-9.\\-]*' }),
+                h('p', { className: 'aria2-rpc-note' }, t('hostHint')),
+                h('div', { className: 'aria2-rpc-pair' }, field('rpcPort', 'port', 6800, 'number', { min: 1, max: 65535, step: 1 }), field('rpcTimeoutMs', 'timeout', 10000, 'number', { min: 1, max: 60000, step: 1 })),
+                h('div', { className: 'aria2-rpc-actions' }, h('button', { type: 'submit', disabled: disabled || !draft }, t(busy ? 'saving' : 'save'))),
+              ),
+              h('fieldset', { disabled: disabled || !credential || !credential.writable || !!draft },
+                h('div', { className: 'aria2-rpc-secret-head' },
+                  h('label', { htmlFor: 'aria2-secret' }, t('secret')),
+                  h('span', { className: `aria2-rpc-status ${credential && credential.configured ? 'configured' : 'missing'}` }, t(credential ? credential.configured ? 'configured' : 'missing' : 'unknown'))),
+                h('input', { id: 'aria2-secret', type: 'password', autoComplete: 'new-password', placeholder: 'rpc-secret', value: secret, onChange: e => setSecret(e.target.value) }),
+                h('p', { className: 'aria2-rpc-note' }, t('secretHint')),
+                h('div', { className: 'aria2-rpc-actions' },
+                  h('button', { type: 'button', disabled: !secret, onClick: () => writeSecret(false) }, t('saveSecret')),
+                  h('button', { type: 'button', disabled: !credential || !credential.configured, onClick: () => writeSecret(true) }, t('clearSecret'))),
+              ),
+              h('div', { className: 'aria2-rpc-actions' }, h('button', { type: 'button', className: `aria2-rpc-test ${testState === 'success' ? 'success' : testState === 'failure' ? 'failure' : ''}`, disabled, onClick: testConnection }, t(testing ? 'testing' : 'test'))),
+              notice && h('p', { role: failed ? 'alert' : 'status', className: `aria2-rpc-note${failed ? ' aria2-rpc-error' : ''}` }, notice),
+            );
+          }
+          ready.slots.inject('plugins.bundle.config', () => ready.slots.register({ name: 'plugins.bundle.config', key: '@rosmeowtis/dsh-aria2-rpc' }, Settings));
+        });
+      },
+    };
+  },
+});

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: aria2-rpc
+      name: '@rosmeowtis/dsh-aria2-rpc'

package/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="14" fill="#146b58"/><g fill="none" stroke="#fff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M32 14v26m-10-9 10 10 10-10M16 42v8h32v-8"/><path d="M14 20h6m24 0h6" opacity=".6"/></g></svg>

package/lib/src/connection-test.d.ts

@@ -0,0 +1,2 @@
+/** Called only behind DSH's authenticated Connection route; never persists drafts. */
+export declare function testConnection(request: Request, resolveSecret: (ref: string) => Promise<string | undefined>, lifetime: AbortSignal): Promise<Response>;

package/lib/src/connection-test.js

@@ -0,0 +1,42 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { Aria2Error, createAria2Client } from './rpc.js';
+/** Called only behind DSH's authenticated Connection route; never persists drafts. */
+export async function testConnection(request, resolveSecret, lifetime) {
+    const respond = (value, status = 200) => Response.json(value, { status, headers: { 'cache-control': 'no-store' } });
+    try {
+        if (!request.headers.get('content-type')?.startsWith('application/json')) {
+            throw new Aria2Error('INVALID_INPUT', 'Expected application/json');
+        }
+        const text = await request.text();
+        if (Buffer.byteLength(text) > 8192)
+            throw new Aria2Error('INVALID_INPUT', 'Connection settings too large');
+        let input;
+        try {
+            input = JSON.parse(text);
+        }
+        catch {
+            throw new Aria2Error('INVALID_INPUT', 'Invalid JSON');
+        }
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            throw new Aria2Error('INVALID_INPUT', 'Expected connection settings');
+        const data = input;
+        if (Object.keys(data).some(key => !['rpcHost', 'rpcPort', 'rpcTimeoutMs', 'rpcSecretRef', 'secret'].includes(key))) {
+            throw new Aria2Error('INVALID_INPUT', 'Unknown connection setting');
+        }
+        if (typeof data.rpcSecretRef !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(data.rpcSecretRef)) {
+            throw new Aria2Error('INVALID_INPUT', 'Invalid credential reference');
+        }
+        if (data.secret !== undefined && (typeof data.secret !== 'string' || !data.secret || data.secret.length > 4096)) {
+            throw new Aria2Error('INVALID_INPUT', 'Invalid secret');
+        }
+        const config = { rpcHost: data.rpcHost, rpcPort: data.rpcPort, timeoutMs: data.rpcTimeoutMs, signal: AbortSignal.any([request.signal, lifetime]) };
+        // Validate host/port/timeouts before accessing a credential or sending anything.
+        createAria2Client(config);
+        const secret = data.secret ?? await resolveSecret(credentialRef(data.rpcSecretRef));
+        const result = await createAria2Client({ ...config, secret }).version();
+        return respond({ ok: true, ...result });
+    }
+    catch (error) {
+        return respond({ ok: false, code: error instanceof Aria2Error ? error.code : 'CREDENTIAL_ERROR' }, error instanceof Aria2Error && error.code === 'INVALID_INPUT' ? 400 : 200);
+    }
+}

package/lib/src/events.d.ts

@@ -0,0 +1,45 @@
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'aria2-rpc': {
+            kind: 'aria2-rpc';
+        };
+    }
+}
+export interface CompletionNotice {
+    gid: string;
+    failed: boolean;
+}
+/** Parse one aria2 WebSocket notification; ignore everything else without throwing. */
+export declare function parseAria2Notification(data: unknown): CompletionNotice | undefined;
+interface Socket {
+    close(): void;
+    send(data: string): void;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: (() => void) | null;
+    onerror: (() => void) | null;
+}
+/**
+ * Keep one WebSocket open for aria2 completion/error notifications.
+ * ponytail: config changes need a plugin reload; reconnect uses the latest host/port.
+ */
+export declare function startAria2Events(options: {
+    endpoint: () => {
+        host: string;
+        port: number;
+    };
+    onNotice: (notice: CompletionNotice) => void;
+    signal: AbortSignal;
+    createSocket?: (url: string) => Socket;
+}): void;
+/** Build one concise, bounded notification after fetching best-effort task details. */
+export declare function describeCompletion(notice: CompletionNotice, config: {
+    host: string;
+    port: number;
+    timeoutMs: number;
+    secret?: string;
+    signal: AbortSignal;
+}): Promise<string>;
+export {};

package/lib/src/events.js

@@ -0,0 +1,98 @@
+import { createAria2Client } from './rpc.js';
+/** Parse one aria2 WebSocket notification; ignore everything else without throwing. */
+export function parseAria2Notification(data) {
+    if (typeof data !== 'string' || data.length > 4096)
+        return undefined;
+    let payload;
+    try {
+        payload = JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const p = payload;
+    if (p.jsonrpc !== '2.0' || (p.method !== 'aria2.onDownloadComplete' && p.method !== 'aria2.onDownloadError'))
+        return undefined;
+    if (!Array.isArray(p.params) || p.params.length !== 1)
+        return undefined;
+    const param = p.params[0];
+    if (!param || typeof param !== 'object' || Array.isArray(param))
+        return undefined;
+    const gid = param.gid;
+    if (typeof gid !== 'string' || !/^(?!0{16}$)[a-f0-9]{16}$/i.test(gid))
+        return undefined;
+    return { gid: gid.toLowerCase(), failed: p.method === 'aria2.onDownloadError' };
+}
+/**
+ * Keep one WebSocket open for aria2 completion/error notifications.
+ * ponytail: config changes need a plugin reload; reconnect uses the latest host/port.
+ */
+export function startAria2Events(options) {
+    const connectSocket = options.createSocket ?? ((url) => new globalThis.WebSocket(url));
+    let socket;
+    let timer;
+    let stopped = false;
+    const schedule = () => {
+        if (stopped)
+            return;
+        timer = setTimeout(connect, 5000);
+    };
+    const connect = () => {
+        if (stopped || options.signal.aborted)
+            return;
+        try {
+            const { host, port } = options.endpoint();
+            const next = connectSocket(`ws://${host}:${port}/jsonrpc`);
+            socket = next;
+            // aria2 starts pushing notifications only after this subscription call.
+            next.onopen = () => {
+                try {
+                    next.send(JSON.stringify({ jsonrpc: '2.0', id: 'aria2-rpc', method: 'system.listNotifications' }));
+                }
+                catch { /* close follows */ }
+            };
+            next.onmessage = (event) => {
+                const notice = parseAria2Notification(event.data);
+                if (notice)
+                    options.onNotice(notice);
+            };
+            next.onclose = () => { if (!stopped)
+                schedule(); };
+            next.onerror = () => { try {
+                next.close();
+            }
+            catch { /* close follows */ } };
+        }
+        catch {
+            schedule();
+        }
+    };
+    const stop = () => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+        try {
+            socket?.close();
+        }
+        catch { /* already gone */ }
+    };
+    options.signal.addEventListener('abort', stop, { once: true });
+    connect();
+}
+/** Build one concise, bounded notification after fetching best-effort task details. */
+export async function describeCompletion(notice, config) {
+    const prefix = notice.failed ? '[aria2] 下载失败' : '[aria2] 下载完成';
+    let detail = '';
+    try {
+        const client = createAria2Client({ rpcHost: config.host, rpcPort: config.port, timeoutMs: config.timeoutMs, secret: config.secret, signal: config.signal });
+        const status = await client.status({ gid: notice.gid });
+        const file = status.files[0]?.path ?? status.directory;
+        detail = notice.failed
+            ? `\n文件：${file}\n错误：${status.errorCode} ${status.error ?? ''}`.trimEnd()
+            : `\n文件：${file}\n大小：${status.totalBytes} 字节`;
+    }
+    catch { /* the event still matters without task details */ }
+    return `${prefix}：${notice.gid}${detail}`;
+}

package/lib/src/index.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "aria2-rpc";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    rpcHost: z<string, string, "volatile-defined">;
+    rpcPort: z<number, number, "volatile-defined">;
+    rpcSecretRef: z<string, string, "volatile-defined">;
+    rpcTimeoutMs: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    rpcHost: z<string, string, "volatile-defined">;
+    rpcPort: z<number, number, "volatile-defined">;
+    rpcSecretRef: z<string, string, "volatile-defined">;
+    rpcTimeoutMs: z<number, number, "volatile-defined">;
+}>>, "plain">;
+type Configuration = ReturnType<typeof Config>;
+export declare function apply(ctx: Context, config: Configuration): void;
+export {};

package/lib/src/index.js

@@ -0,0 +1,172 @@
+import z from '@deepseek-ai/schemastery';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { Aria2Error, createAria2Client } from './rpc.js';
+import { testConnection } from './connection-test.js';
+import { describeCompletion, startAria2Events } from './events.js';
+export const name = 'aria2-rpc';
+export const inject = ['tools', 'credentials', 'sandboxPolicy', 'agents'];
+export const Config = z.object({
+    // Settings schemas cross to the browser: use serializable constraints, never Node callbacks.
+    rpcHost: z.string().pattern(/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*\.?$/i).default('127.0.0.1').volatile(),
+    rpcPort: z.natural().min(1).max(65535).default(6800).volatile(),
+    rpcSecretRef: z.string().pattern(/^[A-Za-z_][A-Za-z0-9_]*$/).role('credential-ref').default('ARIA2_RPC_SECRET').volatile(),
+    rpcTimeoutMs: z.natural().min(1).max(60000).default(10000).volatile(),
+});
+const gidSchema = { type: 'string', pattern: '^[0-9a-fA-F]{16}$', description: '完整的 aria2 GID。作用于当前配置的 RPC 服务，可包含该服务已有的任务。' };
+const schema = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+export function apply(ctx, config) {
+    ctx.inject(['connection'], ready => {
+        const lifetime = new AbortController();
+        ready.effect(() => () => lifetime.abort());
+        // Connection owns browser authentication and Host/Origin checks for /api routes.
+        ready.connection.fetch.register({
+            path: '/api/aria2-rpc.test', methods: ['POST'], requestBody: 'buffered',
+            fetch: request => testConnection(request, async (ref) => (await ready.credentials.resolve(credentialRef(ref)))?.value, lifetime.signal),
+        });
+    });
+    ctx.inject(['settings'], ready => {
+        ready.effect(() => ready.settings.configure({ auto: false }, ctx.fiber));
+    });
+    ctx.effect(() => {
+        const lifetime = new AbortController();
+        const disposers = [];
+        const tracked = new Map();
+        const pending = new Map();
+        const logger = ctx.logger;
+        const notify = async (sessionId, notice) => {
+            const agent = ctx.agents.get(sessionId);
+            if (!agent)
+                return;
+            let secret;
+            try {
+                secret = (await ctx.credentials.resolve(credentialRef(config.rpcSecretRef.get())))?.value;
+            }
+            catch { /* no credential: still push */ }
+            const text = await describeCompletion(notice, {
+                host: config.rpcHost.get(), port: config.rpcPort.get(), timeoutMs: config.rpcTimeoutMs.get(), secret, signal: lifetime.signal,
+            });
+            agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'aria2-rpc' } }));
+            logger?.info?.(`[aria2-rpc] completion notification queued for ${sessionId}: ${notice.gid}`);
+        };
+        const handleNotice = (notice) => {
+            logger?.info?.(`[aria2-rpc] ${notice.failed ? 'error' : 'complete'} event: ${notice.gid}`);
+            const sessionId = tracked.get(notice.gid);
+            if (sessionId === undefined) {
+                pending.set(notice.gid, notice.failed);
+                if (pending.size > 50) {
+                    const oldest = pending.keys().next().value;
+                    if (oldest !== undefined)
+                        pending.delete(oldest);
+                }
+                return;
+            }
+            tracked.delete(notice.gid);
+            void notify(sessionId, notice).catch(() => { });
+        };
+        startAria2Events({
+            endpoint: () => ({ host: config.rpcHost.get(), port: config.rpcPort.get() }),
+            onNotice: handleNotice,
+            signal: lifetime.signal,
+        });
+        const register = (definition) => {
+            disposers.push(ctx.tools.register({
+                ...definition,
+                async execute(args, exec) {
+                    const result = await definition.execute(args, exec);
+                    // DSH replaces cancelled successes; retain the queryable GID as an error instead.
+                    if (exec.signal.aborted && result && typeof result === 'object' && 'outcome' in result && result.outcome === 'unknown_effect') {
+                        throw new Error(JSON.stringify(result));
+                    }
+                    return result;
+                },
+                timeoutMs: 65000,
+                output: {
+                    schema: { type: 'object', additionalProperties: true },
+                    render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+                },
+                presentCall: () => ({ card: 'generic', title: definition.name, kind: definition.name === 'aria2_status' || definition.name === 'aria2_list' ? 'read' : 'execute' }),
+            }));
+        };
+        const run = async (method, args, exec) => {
+            if (method !== 'status' && method !== 'list') {
+                const agent = exec.agent && ctx.agents.get(exec.agent.id);
+                const plan = agent?.ctx.get('planMode');
+                if (!agent || plan?.get(agent).active || plan?.get(agent).pending === true || ctx.sandboxPolicy.resolve({ session: agent.session }).mode !== 'danger-full-access') {
+                    return { ok: false, error: { code: 'PERMISSION_DENIED', message: '创建和控制下载仅允许在退出计划模式后的完全访问模式执行；未发送 RPC。' } };
+                }
+            }
+            try {
+                const rpcHost = config.rpcHost.get();
+                const rpcPort = config.rpcPort.get();
+                const timeoutMs = config.rpcTimeoutMs.get();
+                const ref = config.rpcSecretRef.get();
+                const secret = (await ctx.credentials.resolve(credentialRef(ref)))?.value;
+                const client = createAria2Client({ rpcHost, rpcPort, timeoutMs, secret, signal: lifetime.signal });
+                // Each boundary validates unknown input again; schemas are discovery, not enforcement.
+                const value = await client[method](args, { signal: exec.signal });
+                if (method === 'download' && exec.agent) {
+                    const result = value;
+                    if (result.outcome === 'ok') {
+                        tracked.set(result.gid, exec.agent.id);
+                        const failed = pending.get(result.gid);
+                        if (failed !== undefined) {
+                            pending.delete(result.gid);
+                            void notify(exec.agent.id, { gid: result.gid, failed }).catch(() => { });
+                        }
+                    }
+                }
+                return { ok: true, ...value };
+            }
+            catch (error) {
+                return { ok: false, error: { code: error instanceof Aria2Error ? error.code : 'CONFIG_OR_CREDENTIAL_ERROR', message: error instanceof Aria2Error ? error.message : '配置或凭据不可用，请检查插件设置。' } };
+            }
+        };
+        register({
+            name: 'aria2_download',
+            description: '向正在运行的 aria2 rpc 服务提交单文件下载链接，立刻返回 GID。不等待完成。文件保存在aria2 rpc所在设备。当下载源明确提供校验和时填写 checksum 参数。结果未知时先用 GID 查状态，不要重复提交。任务完成或失败时，插件会向发起会话推送通知。',
+            parameters: schema({
+                url: { type: 'string', description: 'HTTP/HTTPS 文件直链，不允许内嵌用户名和密码。' },
+                directory: { type: 'string', description: 'aria2 所在机器的绝对目录；省略使用其默认目录。' },
+                filename: { type: 'string', description: '纯文件名，不含目录；省略由 aria2 决定。禁止覆盖和自动改名。' },
+                checksum: { ...schema({
+                        algorithm: { type: 'string', enum: ['sha-256', 'sha-1', 'md5'] },
+                        digest: { type: 'string', description: '下载源提供的十六进制摘要：SHA-256 为 64 位，SHA-1 为 40 位，MD5 为 32 位。没有来源校验和时省略整个 checksum。' },
+                    }, ['algorithm', 'digest']) },
+                proxy: { type: 'string', description: '省略继承 aria2 代理；空串直连；http://host:port 为本任务独立 HTTP 代理。不支持 SOCKS 或代理凭据。' },
+            }, ['url']),
+            execute: (args, exec) => run('download', args, exec),
+        });
+        register({
+            name: 'aria2_status',
+            description: '读取当前 RPC 服务中的一个任务状态、速度、文件路径和脱敏错误。不启动下载、不等待完成；complete 不单独证明曾执行哈希校验。',
+            parameters: schema({ gid: gidSchema }, ['gid']),
+            isConcurrencySafe: () => true,
+            execute: (args, exec) => run('status', args, exec),
+        });
+        register({
+            name: 'aria2_list',
+            description: '列出当前 RPC 服务中的任务：active、waiting、stopped 或全部。只读，不创建或修改任务。limit 限制每个分类的数量；offset 用于 waiting/stopped 分页，active 在本地按相同范围截取。',
+            parameters: schema({
+                state: { type: 'string', enum: ['active', 'waiting', 'stopped', 'all'], default: 'all', description: '要查看的任务分类；默认 all。' },
+                limit: { type: 'integer', minimum: 1, maximum: 100, default: 20, description: '每个分类最多返回多少条。' },
+                offset: { type: 'integer', minimum: 0, maximum: 1000000, default: 0, description: '跳过前面的任务；用于 waiting/stopped 分页。' },
+            }, []),
+            isConcurrencySafe: () => true,
+            execute: (args, exec) => run('list', args, exec),
+        });
+        register({
+            name: 'aria2_control',
+            description: '暂停、恢复或取消当前 RPC 服务中的任务。取消不会删除文件、不关闭 aria2；恢复仅适用于暂停任务。动作被接受后可查状态确认，结果未知时不盲目重试。',
+            parameters: schema({ gid: gidSchema, action: { type: 'string', enum: ['pause', 'resume', 'cancel'] } }, ['gid', 'action']),
+            execute: (args, exec) => run('control', args, exec),
+        });
+        return () => {
+            lifetime.abort();
+            tracked.clear();
+            pending.clear();
+            for (const dispose of disposers.reverse())
+                dispose();
+        };
+    });
+}

package/lib/src/rpc.d.ts

@@ -0,0 +1,117 @@
+export type Aria2ErrorCode = 'INVALID_INPUT' | 'RPC_ERROR' | 'HTTP_ERROR' | 'REDIRECT' | 'BAD_RESPONSE' | 'RESPONSE_TOO_LARGE' | 'NETWORK' | 'TIMEOUT' | 'ABORTED';
+/** Messages and enumerable fields are safe for Host display; raw remote errors are never attached. */
+export declare class Aria2Error extends Error {
+    code: Aria2ErrorCode;
+    requestSent: boolean;
+    constructor(code: Aria2ErrorCode, message: string, requestSent?: boolean);
+}
+export interface Aria2ClientConfig {
+    rpcHost: string;
+    rpcPort: number;
+    secret?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface Aria2Checksum {
+    algorithm: 'sha-256' | 'sha-1' | 'md5';
+    digest: string;
+}
+export interface Aria2DownloadArgs {
+    url: string;
+    directory?: string;
+    filename?: string;
+    checksum?: Aria2Checksum;
+    /** undefined inherits aria2 config; '' is direct; otherwise an unauthenticated HTTP proxy. */
+    proxy?: string;
+}
+export interface Aria2StatusArgs {
+    gid: string;
+}
+export type Aria2ControlAction = 'pause' | 'resume' | 'cancel';
+export interface Aria2ControlArgs {
+    gid: string;
+    action: Aria2ControlAction;
+}
+export interface Aria2FileEntry {
+    path: string;
+    length: string;
+    completedLength: string;
+}
+export interface Aria2StatusResult {
+    gid: string;
+    status: 'active' | 'waiting' | 'paused' | 'error' | 'complete' | 'removed';
+    totalBytes: string;
+    completedBytes: string;
+    downloadSpeed: string;
+    uploadSpeed: string;
+    connections: string;
+    directory: string;
+    files: Aria2FileEntry[];
+    filesTruncated: boolean;
+    /** Fraction 0..1, rounded down to four decimal places; null for unknown total size. */
+    progress: number | null;
+    errorCode: string;
+    error: string | null;
+}
+export type Aria2ListState = 'active' | 'waiting' | 'stopped' | 'all';
+export interface Aria2ListArgs {
+    state?: Aria2ListState;
+    limit?: number;
+    offset?: number;
+}
+export interface Aria2TaskSummary {
+    gid: string;
+    status: Aria2StatusResult['status'];
+    totalBytes: string;
+    completedBytes: string;
+    downloadSpeed: string;
+    connections: string;
+    directory: string;
+    file: string | null;
+    progress: number | null;
+    errorCode: string;
+    error: string | null;
+}
+export interface Aria2ListResult {
+    state: Aria2ListState;
+    offset: number;
+    limit: number;
+    active?: Aria2TaskSummary[];
+    waiting?: Aria2TaskSummary[];
+    stopped?: Aria2TaskSummary[];
+}
+export type Aria2MutateResult<T> = ({
+    outcome: 'ok';
+} & T) | ({
+    outcome: 'unknown_effect';
+    code: 'UNKNOWN_EFFECT';
+    reason: string;
+} & T);
+export type Aria2DownloadResult = Aria2MutateResult<{
+    gid: string;
+}>;
+export type Aria2ControlResult = Aria2MutateResult<{
+    gid: string;
+    action: Aria2ControlAction;
+}>;
+export interface Aria2Client {
+    version(opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        version: string;
+    }>;
+    download(args: Aria2DownloadArgs, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Aria2DownloadResult>;
+    status(args: Aria2StatusArgs, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Aria2StatusResult>;
+    list(args: Aria2ListArgs, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Aria2ListResult>;
+    control(args: Aria2ControlArgs, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Aria2ControlResult>;
+}
+export declare function validateHost(host: unknown): string;
+export declare function createAria2Client(config: Aria2ClientConfig): Aria2Client;

package/lib/src/rpc.js

@@ -0,0 +1,363 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { isIP } from 'node:net';
+/** Messages and enumerable fields are safe for Host display; raw remote errors are never attached. */
+export class Aria2Error extends Error {
+    code;
+    requestSent;
+    constructor(code, message, requestSent = false) {
+        super(message);
+        this.name = 'Aria2Error';
+        this.code = code;
+        this.requestSent = requestSent;
+    }
+}
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const DNS_NAME = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*\.?$/i;
+const GID = /^(?!0{16}$)[a-f0-9]{16}$/i;
+const DECIMAL = /^[0-9]+$/;
+const CONTROL_CHARS = /[\x00-\x1f\x7f]/;
+const CHECKSUM_LENGTH = { 'sha-256': 64, 'sha-1': 40, md5: 32 };
+const METHODS = { pause: 'aria2.pause', resume: 'aria2.unpause', cancel: 'aria2.remove' };
+const STATUS_KEYS = ['gid', 'status', 'totalLength', 'completedLength', 'downloadSpeed',
+    'uploadSpeed', 'connections', 'dir', 'files', 'errorCode'];
+const STATUSES = ['active', 'waiting', 'paused', 'error', 'complete', 'removed'];
+function fail(code, message) { throw new Aria2Error(code, message); }
+function object(value, label) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        fail('INVALID_INPUT', `${label}: expected a plain object`);
+    }
+    return value;
+}
+function fields(value, allowed, label) {
+    const result = object(value, label);
+    if (Reflect.ownKeys(result).some((key) => typeof key !== 'string' || !allowed.includes(key))) {
+        fail('INVALID_INPUT', `${label}: unknown field`);
+    }
+    return result;
+}
+function integer(value, label, max) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > max) {
+        fail('INVALID_INPUT', `${label}: expected integer 1..${max}`);
+    }
+    return value;
+}
+function lifecycle(value) {
+    if (value !== undefined && !(value instanceof AbortSignal))
+        fail('INVALID_INPUT', 'signal: expected AbortSignal');
+    return value;
+}
+function gidValue(value) {
+    if (typeof value !== 'string' || !GID.test(value))
+        fail('INVALID_INPUT', 'gid: expected nonzero 16 hex characters');
+    return value.toLowerCase();
+}
+function urlValue(value, proxy = false) {
+    if (typeof value !== 'string' || !value || value.trim() !== value || CONTROL_CHARS.test(value)) {
+        fail('INVALID_INPUT', `${proxy ? 'proxy' : 'url'}: invalid URL`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        fail('INVALID_INPUT', `${proxy ? 'proxy' : 'url'}: invalid URL`);
+    }
+    if (!(proxy ? parsed.protocol === 'http:' : ['http:', 'https:'].includes(parsed.protocol))
+        || !parsed.hostname || parsed.username || parsed.password
+        || value.slice(value.indexOf('//') + 2).split(/[/?#]/, 1)[0]?.includes('@')
+        || (proxy && (parsed.pathname !== '/' || parsed.search || parsed.hash))) {
+        fail('INVALID_INPUT', `${proxy ? 'proxy' : 'url'}: disallowed scheme, credentials or proxy path`);
+    }
+    return value;
+}
+function downloadOptions(args, gid) {
+    fields(args, ['url', 'directory', 'filename', 'checksum', 'proxy'], 'download args');
+    const options = { gid, 'allow-overwrite': 'false', 'auto-file-renaming': 'false' };
+    if (args.directory !== undefined) {
+        const dir = args.directory;
+        if (typeof dir !== 'string' || CONTROL_CHARS.test(dir)
+            || !(dir.startsWith('/') || /^[a-z]:[\\/]/i.test(dir) || /^\\\\[^\\/]+[\\/][^\\/]+/.test(dir))) {
+            fail('INVALID_INPUT', 'directory: expected aria2-side absolute POSIX, drive or UNC path');
+        }
+        options.dir = dir;
+    }
+    if (args.filename !== undefined) {
+        const name = args.filename;
+        if (typeof name !== 'string' || !name || name === '.' || name === '..'
+            || /[\\/:]/.test(name) || CONTROL_CHARS.test(name)) {
+            fail('INVALID_INPUT', 'filename: expected pure file name');
+        }
+        options.out = name;
+    }
+    if (args.checksum !== undefined) {
+        const checksum = fields(args.checksum, ['algorithm', 'digest'], 'checksum');
+        const algorithm = checksum.algorithm;
+        if (algorithm !== 'sha-256' && algorithm !== 'sha-1' && algorithm !== 'md5') {
+            fail('INVALID_INPUT', 'checksum.algorithm: expected sha-256, sha-1 or md5');
+        }
+        if (typeof checksum.digest !== 'string' || checksum.digest.length !== CHECKSUM_LENGTH[algorithm]
+            || !/^[a-f0-9]+$/i.test(checksum.digest)) {
+            fail('INVALID_INPUT', 'checksum.digest: invalid hex length or characters');
+        }
+        options.checksum = `${algorithm}=${checksum.digest.toLowerCase()}`;
+        options['check-integrity'] = 'true';
+    }
+    if (args.proxy !== undefined) {
+        const proxy = args.proxy === '' ? '' : urlValue(args.proxy, true);
+        for (const key of ['all-proxy', 'http-proxy', 'https-proxy'])
+            options[key] = proxy;
+        for (const key of ['no-proxy', 'all-proxy-user', 'all-proxy-passwd', 'http-proxy-user',
+            'http-proxy-passwd', 'https-proxy-user', 'https-proxy-passwd'])
+            options[key] = '';
+    }
+    return options;
+}
+async function responseText(response) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > MAX_RESPONSE_BYTES) {
+                await reader.cancel().catch(() => { });
+                fail('RESPONSE_TOO_LARGE', 'aria2 response exceeds 1 MiB');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, length).toString('utf8');
+}
+function remoteString(value, decimal = false) {
+    if (typeof value !== 'string' || (decimal && !DECIMAL.test(value))) {
+        fail('BAD_RESPONSE', 'aria2 returned invalid status fields');
+    }
+    return value;
+}
+function statusResult(value, gid) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('BAD_RESPONSE', 'aria2 status is not an object');
+    const r = value;
+    if (r.gid !== gid || !STATUSES.includes(r.status) || !Array.isArray(r.files)) {
+        fail('BAD_RESPONSE', 'aria2 returned invalid status fields');
+    }
+    const totalBytes = remoteString(r.totalLength, true);
+    const completedBytes = remoteString(r.completedLength, true);
+    const errorCode = r.errorCode === undefined ? '0' : remoteString(r.errorCode, true);
+    const total = BigInt(totalBytes);
+    const completed = BigInt(completedBytes);
+    const progress = total === 0n ? null : Number((completed > total ? total : completed) * 10000n / total) / 10000;
+    return {
+        gid, status: r.status, totalBytes, completedBytes,
+        downloadSpeed: remoteString(r.downloadSpeed, true), uploadSpeed: remoteString(r.uploadSpeed, true),
+        connections: remoteString(r.connections, true), directory: remoteString(r.dir),
+        files: r.files.slice(0, 20).map((entry) => {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                fail('BAD_RESPONSE', 'aria2 returned invalid file fields');
+            const f = entry;
+            return { path: remoteString(f.path), length: remoteString(f.length, true),
+                completedLength: remoteString(f.completedLength, true) };
+        }),
+        filesTruncated: r.files.length > 20, progress, errorCode,
+        error: errorCode === '0' ? null : errorCode === '32' ? 'Checksum validation failed'
+            : errorCode === '3' ? 'Resource not found' : errorCode === '9' ? 'Insufficient disk space'
+                : errorCode === '13' ? 'File already exists' : 'Download failed',
+    };
+}
+function taskSummary(status) {
+    return {
+        gid: status.gid, status: status.status, totalBytes: status.totalBytes, completedBytes: status.completedBytes,
+        downloadSpeed: status.downloadSpeed, connections: status.connections, directory: status.directory,
+        file: status.files[0]?.path ?? null, progress: status.progress, errorCode: status.errorCode, error: status.error,
+    };
+}
+function listItem(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('BAD_RESPONSE', 'aria2 returned an invalid task entry');
+    const gid = value.gid;
+    return statusResult(value, gidValue(gid));
+}
+function listItems(value) {
+    if (!Array.isArray(value))
+        fail('BAD_RESPONSE', 'aria2 returned an invalid task list');
+    return value.map(listItem);
+}
+function offsetValue(value) {
+    if (value === undefined)
+        return 0;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 1_000_000) {
+        fail('INVALID_INPUT', 'offset: expected integer 0..1000000');
+    }
+    return value;
+}
+function mutationFailure(error, data) {
+    if (error instanceof Aria2Error && error.requestSent && error.code !== 'RPC_ERROR') {
+        return { ...data, outcome: 'unknown_effect', code: 'UNKNOWN_EFFECT', reason: error.code };
+    }
+    throw error;
+}
+export function validateHost(host) {
+    if (typeof host !== 'string' || (!isIP(host) && (!DNS_NAME.test(host) || /^[0-9.]+$/.test(host))) || isIP(host) === 6) {
+        fail('INVALID_INPUT', 'rpcHost: expected DNS name or IPv4 (no scheme, port, path or IPv6)');
+    }
+    // URL parsing must not reinterpret DNS-looking input as a legacy numeric IPv4 address.
+    try {
+        if (new URL(`http://${host}/`).hostname !== host.toLowerCase())
+            throw new Error();
+    }
+    catch {
+        fail('INVALID_INPUT', 'rpcHost: unsupported DNS name or IPv4 spelling');
+    }
+    return host;
+}
+export function createAria2Client(config) {
+    fields(config, ['rpcHost', 'rpcPort', 'secret', 'timeoutMs', 'signal'], 'config');
+    const host = validateHost(config.rpcHost);
+    const port = integer(config.rpcPort, 'rpcPort', 65535);
+    const timeoutMs = config.timeoutMs === undefined ? 10000 : integer(config.timeoutMs, 'timeoutMs', 60000);
+    if (config.secret !== undefined && (typeof config.secret !== 'string' || !config.secret)) {
+        fail('INVALID_INPUT', 'secret: expected non-empty string');
+    }
+    const secret = config.secret;
+    const clientSignal = lifecycle(config.signal);
+    const endpoint = `http://${host}:${port}/jsonrpc`;
+    function signalFor(opts) {
+        if (opts === undefined)
+            return undefined;
+        return lifecycle(fields(opts, ['signal'], 'request options').signal);
+    }
+    async function rpc(method, params, callSignal) {
+        if (clientSignal?.aborted || callSignal?.aborted)
+            fail('ABORTED', 'aria2 request aborted before sending');
+        const id = randomUUID();
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = AbortSignal.any([timeout, ...[clientSignal, callSignal].filter((s) => !!s)]);
+        try {
+            const response = await fetch(endpoint, {
+                method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json' },
+                body: JSON.stringify({ jsonrpc: '2.0', id, method, params: secret === undefined ? params : [`token:${secret}`, ...params] }),
+                redirect: 'manual', signal,
+            });
+            if (response.status >= 300 && response.status < 400) {
+                void response.body?.cancel().catch(() => { });
+                fail('REDIRECT', 'aria2 endpoint redirect rejected');
+            }
+            if (response.status !== 200) {
+                void response.body?.cancel().catch(() => { });
+                fail('HTTP_ERROR', `aria2 endpoint returned HTTP ${response.status}`);
+            }
+            const text = await responseText(response);
+            let payload;
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                fail('BAD_RESPONSE', 'aria2 returned invalid JSON');
+            }
+            if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+                fail('BAD_RESPONSE', 'aria2 returned invalid JSON-RPC envelope');
+            const p = payload;
+            const hasResult = Object.hasOwn(p, 'result');
+            const hasError = Object.hasOwn(p, 'error');
+            if (p.jsonrpc !== '2.0' || p.id !== id || hasResult === hasError)
+                fail('BAD_RESPONSE', 'aria2 returned invalid JSON-RPC envelope or id');
+            if (hasError) {
+                if (!p.error || typeof p.error !== 'object' || Array.isArray(p.error)
+                    || !Number.isInteger(p.error.code)
+                    || typeof p.error.message !== 'string') {
+                    fail('BAD_RESPONSE', 'aria2 returned malformed RPC error');
+                }
+                fail('RPC_ERROR', 'aria2 rejected the request (task may not exist or RPC authorization failed)');
+            }
+            return p.result;
+        }
+        catch (error) {
+            if (error instanceof Aria2Error) {
+                error.requestSent = true;
+                throw error;
+            }
+            const code = timeout.aborted ? 'TIMEOUT' : signal.aborted ? 'ABORTED' : 'NETWORK';
+            throw new Aria2Error(code, `aria2 request ${code.toLowerCase()}`, true);
+        }
+    }
+    return {
+        async version(opts) {
+            const result = await rpc('aria2.getVersion', [], signalFor(opts));
+            const version = result && typeof result === 'object' && !Array.isArray(result)
+                ? result.version : undefined;
+            if (typeof version !== 'string' || !/^[0-9]+\.[0-9]+(?:\.[0-9]+)?(?:[-+][A-Za-z0-9.-]+)?$/.test(version) || version.length > 64) {
+                fail('BAD_RESPONSE', 'aria2 returned invalid version information');
+            }
+            return { version };
+        },
+        async download(args, opts) {
+            const gid = (() => { let value; do {
+                value = randomBytes(8).toString('hex');
+            } while (!GID.test(value)); return value; })();
+            const options = downloadOptions(args, gid);
+            const url = urlValue(args.url);
+            const signal = signalFor(opts);
+            try {
+                const result = await rpc('aria2.addUri', [[url], options], signal);
+                if (result !== gid)
+                    throw new Aria2Error('BAD_RESPONSE', 'aria2 returned an unexpected download gid', true);
+                return { outcome: 'ok', gid };
+            }
+            catch (error) {
+                return mutationFailure(error, { gid });
+            }
+        },
+        async status(args, opts) {
+            const gid = gidValue(fields(args, ['gid'], 'status args').gid);
+            return statusResult(await rpc('aria2.tellStatus', [gid, STATUS_KEYS], signalFor(opts)), gid);
+        },
+        async list(args, opts) {
+            const a = fields(args, ['state', 'limit', 'offset'], 'list args');
+            const state = a.state === undefined ? 'all' : a.state;
+            if (state !== 'active' && state !== 'waiting' && state !== 'stopped' && state !== 'all') {
+                fail('INVALID_INPUT', 'state: expected active, waiting, stopped or all');
+            }
+            const limit = a.limit === undefined ? 20 : integer(a.limit, 'limit', 100);
+            const offset = offsetValue(a.offset);
+            const signal = signalFor(opts);
+            const result = { state, offset, limit };
+            if (state === 'active' || state === 'all') {
+                const active = listItems(await rpc('aria2.tellActive', [STATUS_KEYS], signal)).map(taskSummary);
+                result.active = active.slice(offset, offset + limit);
+            }
+            if (state === 'waiting' || state === 'all') {
+                result.waiting = listItems(await rpc('aria2.tellWaiting', [offset, limit, STATUS_KEYS], signal)).map(taskSummary);
+            }
+            if (state === 'stopped' || state === 'all') {
+                result.stopped = listItems(await rpc('aria2.tellStopped', [offset, limit, STATUS_KEYS], signal)).map(taskSummary);
+            }
+            return result;
+        },
+        async control(args, opts) {
+            const a = fields(args, ['gid', 'action'], 'control args');
+            const gid = gidValue(a.gid);
+            const action = a.action;
+            if (action !== 'pause' && action !== 'resume' && action !== 'cancel')
+                fail('INVALID_INPUT', 'action: expected pause, resume or cancel');
+            const signal = signalFor(opts);
+            try {
+                const result = await rpc(METHODS[action], [gid], signal);
+                if (result !== gid)
+                    throw new Aria2Error('BAD_RESPONSE', 'aria2 returned an unexpected control gid', true);
+                return { outcome: 'ok', gid, action };
+            }
+            catch (error) {
+                return mutationFailure(error, { gid, action });
+            }
+        },
+    };
+}

package/locale/en.json

@@ -0,0 +1 @@
+{"meta":{"title":"Aria2 RPC","description":"Connect to an existing aria2 RPC service to create, inspect, pause, resume or cancel downloads. No bundled aria2."}}

package/locale/zh.json

@@ -0,0 +1 @@
+{"meta":{"title":"Aria2 RPC","description":"连接已有 aria2 RPC 服务，创建、查看、暂停、恢复或取消下载；不附带 aria2。"}}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@rosmeowtis/dsh-aria2-rpc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Control an existing aria2 JSON-RPC service from DSH. No bundled downloader.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rosmeowtis/dsh-aria2-rpc.git"
+  },
+  "type": "module",
+  "main": "./lib/src/index.js",
+  "types": "./lib/src/index.d.ts",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": {
+      "types": "./lib/src/index.d.ts",
+      "import": "./lib/src/index.js"
+    },
+    "./client": "./client.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "lib/src",
+    "client.js",
+    "locale/*.json",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.18",
+    "dsh": "^0.2.1-rc.5"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --check client.js && node --test lib/test/*.test.js",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-credentials": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-connection": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-plan-mode": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-settings": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.5",
+    "@types/node": "^22.0.0",
+    "typescript": "~5.9.3"
+  }
+}