@actiondock/core 2.6.0 → 2.8.0

package/dist/server/routes/runs.js

@@ -1,5 +1,4 @@
-import { filterByIntent } from "../../filter/index.js";
-import { EXECUTION_FAILED } from "../../errors.js";
+import { CAPABILITY_UNAVAILABLE, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, EXECUTION_FAILED, PACKAGE_FORBIDDEN, RUN_ALREADY_FINISHED, RUN_INTERRUPTED, RUN_NOT_FOUND, RUNS_CLEAR_ERROR, RUNS_LIST_ERROR, } from "../../errors.js";
 import { isTerminalRunStatus } from "../../storage/types.js";
 import { readJsonBody } from "../body.js";
 import { getSubPath, jsonResponse } from "./common.js";
@@ -7,7 +6,7 @@ import { getSubPath, jsonResponse } from "./common.js";
  * 处理历史运行记录查询、清理、详情及 SSE 流式日志接口。
  */
 export async function handleRunsRoutes(ctx) {
-    const { req, url, pathname, corsHeaders, options, target, host } = ctx;
+    const { req, url, pathname, corsHeaders, options, service } = ctx;
     const subpath = getSubPath(pathname);
     // 1. Runs List: GET /api/v2/runs, GET /runs
     if (subpath === "/runs" && req.method === "GET") {
@@ -16,7 +15,11 @@ export async function handleRunsRoutes(ctx) {
             const actionId = url.searchParams.get("actionId") || undefined;
             const packageId = url.searchParams.get("packageId") || undefined;
             const intent = url.searchParams.get("intent") || undefined;
-            const limit = parseInt(url.searchParams.get("limit") || "50", 10);
+            // limit 边界防护：非法或超界值回退默认 50，并夹紧到 1 至 500 区间
+            const parsedLimit = parseInt(url.searchParams.get("limit") || "50", 10);
+            const limit = Number.isFinite(parsedLimit) && parsedLimit > 0
+                ? Math.min(parsedLimit, 500)
+                : 50;
             if (packageId &&
                 options.packageAllowlist &&
                 options.packageAllowlist.length > 0 &&
@@ -24,61 +27,26 @@ export async function handleRunsRoutes(ctx) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_FORBIDDEN",
+                        code: PACKAGE_FORBIDDEN,
                         message: `Package '${packageId}' is not in the allowed package list`,
                     },
                 }, 403, corsHeaders);
             }
-            const allRuns = [];
-            const seenRunIds = new Set();
-            const apps = host
-                ? host.listApps()
-                : (() => {
-                    const inner = target?.unwrap?.();
-                    return inner && "listApps" in inner ? inner.listApps() : [inner].filter(Boolean);
-                })();
-            for (const app of apps) {
-                if (!app)
-                    continue;
-                if (packageId && app.packageId !== packageId)
-                    continue;
-                if (options.packageAllowlist && options.packageAllowlist.length > 0) {
-                    if (!options.packageAllowlist.includes(app.packageId)) {
-                        continue;
-                    }
-                }
-                if (app.storage && typeof app.storage.listRuns === "function") {
-                    try {
-                        // 状态过滤下推到存储层 SQL，避免先分页后过滤导致某包前 N 条非目标状态时贡献 0 条
-                        const records = app.storage.listRuns({ actionId, status, limit });
-                        for (const r of records) {
-                            if (!seenRunIds.has(r.id)) {
-                                seenRunIds.add(r.id);
-                                if (options.packageAllowlist &&
-                                    options.packageAllowlist.length > 0 &&
-                                    r.packageId &&
-                                    !options.packageAllowlist.includes(r.packageId)) {
-                                    continue;
-                                }
-                                allRuns.push(r);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        // 单包查询失败不阻断整体列表响应，但必须可观测
-                        console.warn(`[actiondock] listRuns failed for package '${app.packageId}': ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
+            let allRuns = await service.runs.list({
+                actionId,
+                status,
+                packageId,
+                intent,
+                limit,
+            });
+            if (options.packageAllowlist && options.packageAllowlist.length > 0) {
+                allRuns = allRuns.filter((r) => !r.packageId || options.packageAllowlist.includes(r.packageId));
             }
-            allRuns.sort((a, b) => (b.startedAt || "").localeCompare(a.startedAt || ""));
-            const filtered = intent
-                ? filterByIntent(allRuns, intent, [(r) => r.id, (r) => r.actionId, (r) => r.status, (r) => r.packageId], false)
-                : allRuns;
-            const sliced = filtered.slice(0, limit);
-            return jsonResponse({ ok: true, total: filtered.length, items: sliced }, 200, corsHeaders);
+            const sliced = allRuns.slice(0, limit);
+            return jsonResponse({ ok: true, total: allRuns.length, items: sliced }, 200, corsHeaders);
         }
         catch (err) {
-            return jsonResponse({ ok: false, error: { code: "RUNS_LIST_ERROR", message: err.message } }, 500, corsHeaders);
+            return jsonResponse({ ok: false, error: { code: RUNS_LIST_ERROR, message: err.message } }, 500, corsHeaders);
         }
     }
     // 2. Runs Clear: POST /api/v2/runs/clear, DELETE /api/v2/runs, etc.
@@ -99,45 +67,28 @@ export async function handleRunsRoutes(ctx) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_FORBIDDEN",
+                        code: PACKAGE_FORBIDDEN,
                         message: `Package '${packageId}' is not in the allowed package list`,
                     },
                 }, 403, corsHeaders);
             }
             let clearedCount = 0;
-            const apps = host
-                ? host.listApps()
-                : (() => {
-                    const inner = target?.unwrap?.();
-                    return inner && "listApps" in inner ? inner.listApps() : [inner].filter(Boolean);
-                })();
-            for (const app of apps) {
-                if (!app)
-                    continue;
-                if (packageId && app.packageId !== packageId)
-                    continue;
-                if (options.packageAllowlist && options.packageAllowlist.length > 0) {
-                    if (!options.packageAllowlist.includes(app.packageId)) {
-                        continue;
-                    }
-                }
-                if (app.storage && typeof app.storage.clearRuns === "function") {
-                    clearedCount += app.storage.clearRuns({ actionId, status });
-                }
+            if (service.runs.clear) {
+                clearedCount = await service.runs.clear({ packageId, actionId, status });
             }
             return jsonResponse({ ok: true, clearedCount }, 200, corsHeaders);
         }
         catch (err) {
-            return jsonResponse({ ok: false, error: { code: "RUNS_CLEAR_ERROR", message: err.message } }, 500, corsHeaders);
+            return jsonResponse({ ok: false, error: { code: RUNS_CLEAR_ERROR, message: err.message } }, 500, corsHeaders);
         }
     }
     // 3. Run Events SSE: GET /api/v2/runs/:runId/events (and stream alias)
     const runEventsMatch = subpath.match(/^\/runs\/([^/]+)\/(events|stream)$/);
     if (runEventsMatch && req.method === "GET") {
         const runId = decodeURIComponent(runEventsMatch[1]);
-        const run = await target.getRun(runId);
+        const run = await service.runs.get(runId);
         if (!run) {
-            return jsonResponse({ ok: false, error: { code: "RUN_NOT_FOUND", message: `Run '${runId}' not found` } }, 404, corsHeaders);
+            return jsonResponse({ ok: false, error: { code: RUN_NOT_FOUND, message: `Run '${runId}' not found` } }, 404, corsHeaders);
         }
         if (options.packageAllowlist &&
             options.packageAllowlist.length > 0 &&
@@ -145,7 +96,7 @@ export async function handleRunsRoutes(ctx) {
             return jsonResponse({
                 ok: false,
                 error: {
-                    code: "PACKAGE_FORBIDDEN",
+                    code: PACKAGE_FORBIDDEN,
                     message: `Package '${run.packageId}' is not in the allowed package list`,
                 },
             }, 403, corsHeaders);
@@ -165,44 +116,62 @@ export async function handleRunsRoutes(ctx) {
                 afterCursor = trimmed;
             }
         }
-        const eventStream = target.events(runId, { after: afterCursor, signal: req.signal });
+        if (!service.events) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: CAPABILITY_UNAVAILABLE,
+                    message: "EventsPort is not supported by this ActionDock service",
+                },
+            }, 501);
+        }
+        const eventStream = service.events.events(runId, { after: afterCursor, signal: req.signal });
         const iterator = eventStream[Symbol.asyncIterator]();
-        // 检查游标是否在建流前已过期：拉取首个事件，若抛出 EVENT_CURSOR_EXPIRED 直接返回 410
+        const encoder = new TextEncoder();
+        const encodeEvent = (evt) => {
+            const eventType = evt.type || "message";
+            const idField = evt.eventId ? `id: ${evt.eventId}\n` : `id: ${evt.sequence}\n`;
+            return encoder.encode(`${idField}event: ${eventType}\ndata: ${JSON.stringify(evt)}\n\n`);
+        };
+        // 游标过期检测：仅等待首事件一小段时间（过期错误通常在拉取瞬间抛出）；
+        // 超时后立即开流，保证响应头及时下发，不再等首事件到达
+        const CURSOR_PROBE_MS = 250;
         let firstResult;
+        let cursorExpired = null;
+        const firstPull = iterator.next();
         try {
-            firstResult = await iterator.next();
+            firstResult = await Promise.race([
+                firstPull,
+                new Promise((resolve) => setTimeout(() => resolve(undefined), CURSOR_PROBE_MS)),
+            ]);
         }
         catch (err) {
-            if (err?.code === "EVENT_CURSOR_EXPIRED") {
-                return jsonResponse({
-                    ok: false,
-                    error: {
-                        code: "EVENT_CURSOR_EXPIRED",
-                        message: err.message || "Event cursor has expired",
-                        details: err.details,
-                    },
-                }, 410, corsHeaders);
-            }
-            throw err;
+            cursorExpired = err;
+        }
+        if (cursorExpired?.code === EVENT_CURSOR_EXPIRED) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: EVENT_CURSOR_EXPIRED,
+                    message: cursorExpired.message || "Event cursor has expired",
+                    details: cursorExpired.details,
+                },
+            }, 410, corsHeaders);
         }
         const stream = new ReadableStream({
             async start(controller) {
-                const encoder = new TextEncoder();
                 let sawFinish = false;
-                let eventsCount = 0;
                 try {
-                    // 先消费首个事件结果
-                    if (!firstResult.done) {
-                        eventsCount++;
-                        const evt = firstResult.value;
+                    // 先消费首个事件结果（探测期内未完成则继续等待）
+                    const first = firstResult ?? (await firstPull);
+                    if (!first.done) {
+                        const evt = first.value;
                         if (evt.type === "finish") {
                             sawFinish = true;
                         }
-                        const eventType = evt.type || "message";
-                        const idField = evt.eventId ? `id: ${evt.eventId}\n` : `id: ${evt.sequence}\n`;
-                        controller.enqueue(encoder.encode(`${idField}event: ${eventType}\ndata: ${JSON.stringify(evt)}\n\n`));
+                        controller.enqueue(encodeEvent(evt));
                         // 若首条事件为背压终止事件，立即关闭通道
-                        if (evt.type === "error" && evt.error?.code === "EVENT_BACKPRESSURE_LIMIT") {
+                        if (evt.type === "error" && evt.error?.code === EVENT_BACKPRESSURE_LIMIT) {
                             controller.close();
                             return;
                         }
@@ -212,16 +181,13 @@ export async function handleRunsRoutes(ctx) {
                         const nextResult = await iterator.next();
                         if (nextResult.done)
                             break;
-                        eventsCount++;
                         const evt = nextResult.value;
                         if (evt.type === "finish") {
                             sawFinish = true;
                         }
-                        const eventType = evt.type || "message";
-                        const idField = evt.eventId ? `id: ${evt.eventId}\n` : `id: ${evt.sequence}\n`;
-                        controller.enqueue(encoder.encode(`${idField}event: ${eventType}\ndata: ${JSON.stringify(evt)}\n\n`));
+                        controller.enqueue(encodeEvent(evt));
                         // 若收到背压截断终止事件，正常关闭流通道
-                        if (evt.type === "error" && evt.error?.code === "EVENT_BACKPRESSURE_LIMIT") {
+                        if (evt.type === "error" && evt.error?.code === EVENT_BACKPRESSURE_LIMIT) {
                             break;
                         }
                     }
@@ -236,7 +202,7 @@ export async function handleRunsRoutes(ctx) {
                                     ok: false,
                                     runId,
                                     error: run.error || {
-                                        code: run.status === "interrupted" ? "RUN_INTERRUPTED" : EXECUTION_FAILED,
+                                        code: run.status === "interrupted" ? RUN_INTERRUPTED : EXECUTION_FAILED,
                                         message: `Run finished with status ${run.status}`,
                                     },
                                 },
@@ -244,8 +210,11 @@ export async function handleRunsRoutes(ctx) {
                         controller.enqueue(encoder.encode(`event: finish\ndata: ${JSON.stringify(finishEvt)}\n\n`));
                     }
                 }
-                catch {
-                    // 忽略中断
+                catch (err) {
+                    // 流中断不静默：保留诊断线索（客户端断连属正常路径，仅记录非预期异常）
+                    if (!(err instanceof Error) || err.name !== "AbortError") {
+                        console.warn(`[RunsRoute] SSE stream for run '${runId}' interrupted: ${err instanceof Error ? err.message : String(err)}`);
+                    }
                 }
                 finally {
                     try {
@@ -254,7 +223,16 @@ export async function handleRunsRoutes(ctx) {
                     catch { }
                 }
             },
-            cancel() { },
+            cancel() {
+                // 客户端断开时释放底层事件迭代器，避免资源悬挂
+                try {
+                    const ret = iterator.return?.();
+                    if (ret && typeof ret.catch === "function") {
+                        ret.catch(() => { });
+                    }
+                }
+                catch { }
+            },
         });
         return new Response(stream, {
             status: 200,
@@ -270,12 +248,12 @@ export async function handleRunsRoutes(ctx) {
     const runShowMatch = subpath.match(/^\/runs\/([^/]+)$/);
     if (runShowMatch && req.method === "GET") {
         const runId = decodeURIComponent(runShowMatch[1]);
-        const run = await target.getRun(runId);
+        const run = await service.runs.get(runId);
         if (!run) {
             return jsonResponse({
                 ok: false,
                 error: {
-                    code: "RUN_NOT_FOUND",
+                    code: RUN_NOT_FOUND,
                     message: `Run '${runId}' not found`,
                 },
             }, 404, corsHeaders);
@@ -286,7 +264,7 @@ export async function handleRunsRoutes(ctx) {
             return jsonResponse({
                 ok: false,
                 error: {
-                    code: "PACKAGE_FORBIDDEN",
+                    code: PACKAGE_FORBIDDEN,
                     message: `Package '${run.packageId || "unknown"}' is not in the allowed package list`,
                 },
             }, 403, corsHeaders);
@@ -298,12 +276,12 @@ export async function handleRunsRoutes(ctx) {
     if (runCancelMatch && req.method === "POST") {
         const runId = decodeURIComponent(runCancelMatch[1]);
         if (options.packageAllowlist && options.packageAllowlist.length > 0) {
-            const run = await target.getRun(runId);
+            const run = await service.runs.get(runId);
             if (run && (!run.packageId || !options.packageAllowlist.includes(run.packageId))) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_FORBIDDEN",
+                        code: PACKAGE_FORBIDDEN,
                         message: `Package '${run.packageId}' is not in the allowed package list`,
                     },
                 }, 403, corsHeaders);
@@ -315,12 +293,12 @@ export async function handleRunsRoutes(ctx) {
         }
         catch { }
         const reason = body?.reason || "Cancelled by client request";
-        const cancelResult = await target.cancelRun(runId, reason);
+        const cancelResult = await service.runs.cancel(runId, reason);
         if (cancelResult.outcome === "not_found") {
             return jsonResponse({
                 ok: false,
                 error: {
-                    code: "RUN_NOT_FOUND",
+                    code: RUN_NOT_FOUND,
                     message: `Run '${runId}' not found`,
                 },
             }, 404, corsHeaders);
@@ -329,7 +307,7 @@ export async function handleRunsRoutes(ctx) {
             return jsonResponse({
                 ok: false,
                 error: {
-                    code: "RUN_ALREADY_FINISHED",
+                    code: RUN_ALREADY_FINISHED,
                     message: `Run '${runId}' has already finished with status '${cancelResult.status}'`,
                     status: cancelResult.status,
                 },

package/dist/server/routes/state.js

@@ -1,13 +1,22 @@
 import { decodeStateKey } from "../../storage/index.js";
-import { CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND } from "../../errors.js";
+import { AMBIGUOUS_STATE_KEY, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, INVALID_PACKAGE_ID, PACKAGE_NOT_ALLOWED, PACKAGE_NOT_FOUND, PATH_TRAVERSAL, STATE_CLEAR_ERROR, STATE_KEY_ERROR, STATE_KEY_NOT_FOUND, STATE_LIST_ERROR, } from "../../errors.js";
 import { readJsonBody } from "../body.js";
-import { assertPackageAllowed, getSubPath, jsonResponse, resolveAppForPackage } from "./common.js";
+import { getSubPath, jsonResponse, resolveTargetPackageId } from "./common.js";
+function isClientStateError(err) {
+    return (err?.code === PACKAGE_NOT_FOUND ||
+        err?.code === INVALID_PACKAGE_ID ||
+        err?.code === PATH_TRAVERSAL ||
+        err?.code === AMBIGUOUS_STATE_KEY ||
+        err?.code === INVALID_ARGUMENT ||
+        err?.status === 400 ||
+        err?.status === 404);
+}
 /**
  * 处理状态键名列表、读取、写入、删除及清空接口。
  * 在未显式开启管理功能 (options.enableManagement !== true) 时返回 403 拒绝。
  */
 export async function handleStateRoutes(ctx) {
-    const { req, url, pathname, corsHeaders, options, host, target } = ctx;
+    const { req, url, pathname, corsHeaders, options, service } = ctx;
     const subpath = getSubPath(pathname);
     const isStateRoute = subpath === "/state" ||
         subpath.startsWith("/state/") ||
@@ -16,7 +25,7 @@ export async function handleStateRoutes(ctx) {
         return null;
     }
     // 校验管理能力开关
-    if (options.enableManagement !== true) {
+    if (options.enableManagement !== true || !service.management?.state) {
         return jsonResponse({
             ok: false,
             error: {
@@ -32,31 +41,26 @@ export async function handleStateRoutes(ctx) {
             const actionParam = url.searchParams.get("action") || url.searchParams.get("actionId") || "";
             const nsParam = url.searchParams.get("namespace") ?? undefined;
             const prefix = url.searchParams.get("prefix") || "";
-            if (pkgParam) {
-                assertPackageAllowed(pkgParam, options);
-            }
-            const app = resolveAppForPackage(pkgParam, host, target, options);
-            assertPackageAllowed(app.packageId, options);
-            const effectiveNs = actionParam
-                ? (nsParam !== undefined ? `${actionParam}:${nsParam}` : actionParam)
-                : (nsParam !== undefined ? nsParam : null);
-            const keys = await app.storage.listStateKeys(effectiveNs, prefix);
-            return jsonResponse({ ok: true, packageId: app.packageId, keys }, 200, corsHeaders);
+            const pkgs = await service.discovery.listPackages();
+            const targetPackageId = resolveTargetPackageId(pkgs, pkgParam, options);
+            const keys = await service.management.state.list(targetPackageId, actionParam, {
+                namespace: nsParam,
+                prefix,
+            });
+            return jsonResponse({ ok: true, packageId: targetPackageId, keys }, 200, corsHeaders);
         }
         catch (err) {
-            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+            if (err.code === PACKAGE_NOT_ALLOWED || err.status === 403) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_NOT_ALLOWED",
+                        code: PACKAGE_NOT_ALLOWED,
                         message: err.message || "Package is not in the allowed package list",
                     },
                 }, 403, corsHeaders);
             }
-            const isClient = err.message?.includes("Unknown or unregistered package") ||
-                err.message?.includes("Invalid packageId") ||
-                err.message?.includes("escapes boundary");
-            return jsonResponse({ ok: false, error: { code: isClient ? "INVALID_ARGUMENT" : "STATE_LIST_ERROR", message: err.message } }, isClient ? 400 : 500, corsHeaders);
+            const isClient = isClientStateError(err);
+            return jsonResponse({ ok: false, error: { code: isClient ? INVALID_ARGUMENT : STATE_LIST_ERROR, message: err.message } }, isClient ? 400 : 500, corsHeaders);
         }
     }
     // 2. State Clear: POST /state/clear
@@ -66,33 +70,27 @@ export async function handleStateRoutes(ctx) {
             const pkgParam = url.searchParams.get("package") || url.searchParams.get("packageId") || body.package || undefined;
             const actionParam = url.searchParams.get("action") || url.searchParams.get("actionId") || body.action || body.actionId || "";
             const baseNs = body.namespace ?? (url.searchParams.get("namespace") || undefined);
-            const effectiveNs = actionParam ? (baseNs ? `${actionParam}:${baseNs}` : actionParam) : baseNs;
-            if (pkgParam) {
-                assertPackageAllowed(pkgParam, options);
-            }
-            const app = resolveAppForPackage(pkgParam, host, target, options);
-            assertPackageAllowed(app.packageId, options);
-            const clearedCount = await app.storage.clearState({
-                namespace: effectiveNs,
+            const pkgs = await service.discovery.listPackages();
+            const targetPackageId = resolveTargetPackageId(pkgs, pkgParam, options);
+            const clearedCount = await service.management.state.clear(targetPackageId, actionParam, {
+                namespace: baseNs,
                 all: Boolean(body.all ?? url.searchParams.get("all") === "true"),
                 prefix: body.prefix ?? (url.searchParams.get("prefix") || undefined),
             });
-            return jsonResponse({ ok: true, packageId: app.packageId, clearedCount }, 200, corsHeaders);
+            return jsonResponse({ ok: true, packageId: targetPackageId, clearedCount }, 200, corsHeaders);
         }
         catch (err) {
-            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+            if (err.code === PACKAGE_NOT_ALLOWED || err.status === 403) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_NOT_ALLOWED",
+                        code: PACKAGE_NOT_ALLOWED,
                         message: err.message || "Package is not in the allowed package list",
                     },
                 }, 403, corsHeaders);
             }
-            const isClient = err.message?.includes("Unknown or unregistered package") ||
-                err.message?.includes("Invalid packageId") ||
-                err.message?.includes("escapes boundary");
-            return jsonResponse({ ok: false, error: { code: isClient ? "INVALID_ARGUMENT" : "STATE_CLEAR_ERROR", message: err.message } }, isClient ? 400 : 500, corsHeaders);
+            const isClient = isClientStateError(err);
+            return jsonResponse({ ok: false, error: { code: isClient ? INVALID_ARGUMENT : STATE_CLEAR_ERROR, message: err.message } }, isClient ? 400 : 500, corsHeaders);
         }
     }
     // 3. State Key CRUD: GET / PUT / POST / DELETE /state/:key
@@ -103,24 +101,26 @@ export async function handleStateRoutes(ctx) {
             const pkgParam = url.searchParams.get("package") || url.searchParams.get("packageId") || undefined;
             const actionParam = url.searchParams.get("action") || url.searchParams.get("actionId") || "";
             const nsParam = url.searchParams.get("namespace") || undefined;
-            const effectiveNs = actionParam ? (nsParam ? `${actionParam}:${nsParam}` : actionParam) : nsParam;
-            if (pkgParam) {
-                assertPackageAllowed(pkgParam, options);
-            }
-            const app = resolveAppForPackage(pkgParam, host, target, options);
-            assertPackageAllowed(app.packageId, options);
+            const pkgs = await service.discovery.listPackages();
+            const targetPackageId = resolveTargetPackageId(pkgs, pkgParam, options);
             if (req.method === "GET") {
-                const entry = await app.storage.findState(key, effectiveNs);
-                if (!entry || entry.value === undefined) {
+                const entry = await service.management.state.get(targetPackageId, actionParam, key, {
+                    namespace: nsParam,
+                    detail: true,
+                });
+                if (!entry || (typeof entry === "object" && entry.value === undefined)) {
                     return jsonResponse({ ok: false, error: { code: STATE_KEY_NOT_FOUND, message: `State key '${key}' not found` } }, 404, corsHeaders);
                 }
+                const data = typeof entry === "object" && "value" in entry
+                    ? entry
+                    : { key, namespace: nsParam || "", value: entry, expiresAt: undefined };
                 return jsonResponse({
                     ok: true,
-                    packageId: app.packageId,
-                    key: entry.key,
-                    namespace: entry.namespace,
-                    value: entry.value,
-                    expiresAt: entry.expiresAt,
+                    packageId: targetPackageId,
+                    key: data.key || key,
+                    namespace: data.namespace ?? nsParam ?? "",
+                    value: data.value,
+                    expiresAt: data.expiresAt,
                 }, 200, corsHeaders);
             }
             if (req.method === "PUT" || req.method === "POST") {
@@ -129,40 +129,41 @@ export async function handleStateRoutes(ctx) {
                 const ttl = typeof body.ttl === "number" ? body.ttl : undefined;
                 const bodyAction = body.action || body.actionId || actionParam;
                 const explicitNs = body.namespace || nsParam;
-                const combinedNs = bodyAction ? (explicitNs ? `${bodyAction}:${explicitNs}` : bodyAction) : explicitNs;
                 let actualKey = key;
-                let ns = combinedNs || "";
-                if (!combinedNs) {
+                let ns = explicitNs;
+                if (!bodyAction && !explicitNs) {
                     const decoded = decodeStateKey(key);
                     ns = decoded.namespace;
                     actualKey = decoded.key;
                 }
-                await app.storage.setState(ns, actualKey, val, ttl);
-                return jsonResponse({ ok: true, packageId: app.packageId, key: actualKey, namespace: ns, message: "updated" }, 200, corsHeaders);
+                await service.management.state.set(targetPackageId, bodyAction, actualKey, val, {
+                    namespace: ns,
+                    ttl,
+                });
+                return jsonResponse({ ok: true, packageId: targetPackageId, key: actualKey, namespace: ns || bodyAction || "", message: "updated" }, 200, corsHeaders);
             }
             if (req.method === "DELETE") {
-                const deleted = await app.storage.deleteStateSmart(key, effectiveNs);
+                const deleted = await service.management.state.delete(targetPackageId, actionParam, key, {
+                    namespace: nsParam,
+                });
                 if (!deleted) {
                     return jsonResponse({ ok: false, error: { code: STATE_KEY_NOT_FOUND, message: `State key '${key}' not found` } }, 404, corsHeaders);
                 }
-                return jsonResponse({ ok: true, packageId: app.packageId, key, deleted: true }, 200, corsHeaders);
+                return jsonResponse({ ok: true, packageId: targetPackageId, key, deleted: true }, 200, corsHeaders);
             }
         }
         catch (err) {
-            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+            if (err.code === PACKAGE_NOT_ALLOWED || err.status === 403) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_NOT_ALLOWED",
+                        code: PACKAGE_NOT_ALLOWED,
                         message: err.message || "Package is not in the allowed package list",
                     },
                 }, 403, corsHeaders);
             }
-            const isClient = err.message?.includes("Unknown or unregistered package") ||
-                err.message?.includes("Invalid packageId") ||
-                err.message?.includes("escapes boundary") ||
-                err.message?.includes("Ambiguous state key");
-            return jsonResponse({ ok: false, error: { code: isClient ? "INVALID_ARGUMENT" : "STATE_KEY_ERROR", message: err.message } }, isClient ? 400 : 500, corsHeaders);
+            const isClient = isClientStateError(err);
+            return jsonResponse({ ok: false, error: { code: isClient ? INVALID_ARGUMENT : STATE_KEY_ERROR, message: err.message } }, isClient ? 400 : 500, corsHeaders);
         }
     }
     return null;

package/dist/server/server.d.ts

@@ -9,7 +9,7 @@ export declare function formatHostForUrl(host: string): string;
  */
 export declare function launchHttpServer(port: number, host: string, fetchHandler: (req: Request) => Promise<Response>, tls?: ServerTlsOptions): Promise<CoreHttpServerInstance>;
 /**
- * 启动 ActionDock 2.0 原生轻量级 HTTP 服务端。
- * 作为 ActionDockHost 与 ActionDockTarget 的薄适配层，负责中间件流转、认证拦截与路由分发。
+ * 启动 ActionDock 原生轻量级 HTTP 服务端。
+ * 面向 ActionDockService 服务端口，负责中间件流转、认证拦截与路由分发。
  */
 export declare function startActionDockServer(options?: ServerOptions): Promise<ActionDockServerInstance>;