@actiondock/core 2.0.12 → 2.2.0

package/dist/server/routes/playbooks.js

@@ -0,0 +1,134 @@
+import { filterByIntent } from "../../filter/index.js";
+import { assertPackageAllowed, getSubPath, jsonResponse } from "./common.js";
+/**
+ * 处理 Playbook 规程相关的 HTTP 路由（列表与 SOP 详情查询）。
+ */
+export async function handlePlaybooksRoutes(ctx) {
+    const { req, url, pathname, corsHeaders, target, host, options } = ctx;
+    const subpath = getSubPath(pathname);
+    // 1. Playbooks List: GET /api/v2/playbooks, GET /playbooks
+    if (subpath === "/playbooks" && req.method === "GET") {
+        try {
+            const intent = url.searchParams.get("intent") || undefined;
+            const targetPkg = url.searchParams.get("package") || url.searchParams.get("packageId") || undefined;
+            if (targetPkg) {
+                assertPackageAllowed(targetPkg, options);
+            }
+            let pbs = await target.listPlaybooks({ intent, package: targetPkg });
+            if (targetPkg) {
+                pbs = pbs.filter((p) => p.packageId === targetPkg);
+            }
+            if (options.packageAllowlist && Array.isArray(options.packageAllowlist) && options.packageAllowlist.length > 0) {
+                pbs = pbs.filter((p) => p.packageId && options.packageAllowlist.includes(p.packageId));
+            }
+            if (intent) {
+                pbs = filterByIntent(pbs, intent, [(p) => p.id, (p) => p.description || "", (p) => p.packageId || "", (p) => (p.actions || []).join(" ")], false);
+            }
+            return jsonResponse(pbs, 200, corsHeaders);
+        }
+        catch (err) {
+            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: "PACKAGE_NOT_ALLOWED",
+                        message: err.message || "Package is not in the allowed package list",
+                    },
+                }, 403, corsHeaders);
+            }
+            return jsonResponse({ ok: false, error: { code: "PLAYBOOKS_LIST_ERROR", message: err.message } }, 500, corsHeaders);
+        }
+    }
+    // 2. Multi-package Playbook Show: GET /api/v2/packages/:packageId/playbooks/:playbookId
+    const pkgPlaybookMatch = subpath.match(/^\/packages\/([^/]+)\/playbooks\/([^/]+)$/);
+    if (pkgPlaybookMatch && req.method === "GET") {
+        const packageId = decodeURIComponent(pkgPlaybookMatch[1]);
+        const playbookId = decodeURIComponent(pkgPlaybookMatch[2]);
+        try {
+            assertPackageAllowed(packageId, options);
+        }
+        catch (err) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: "PACKAGE_NOT_ALLOWED",
+                    message: err.message || `Package '${packageId}' is not in the allowed package list`,
+                },
+            }, 403, corsHeaders);
+        }
+        const ref = `${packageId}/${playbookId}`;
+        try {
+            const pb = await target.describePlaybook(ref);
+            return jsonResponse(pb, 200, corsHeaders);
+        }
+        catch (err) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: "PLAYBOOK_NOT_FOUND",
+                    message: err.message || `Playbook '${playbookId}' not found in package '${packageId}'`,
+                },
+            }, 404, corsHeaders);
+        }
+    }
+    // 3. Short Playbook Show: GET /api/v2/playbooks/:id, GET /playbooks/:id
+    const playbookMatch = subpath.match(/^\/playbooks\/(.+)$/);
+    if (playbookMatch && req.method === "GET") {
+        const playbookId = decodeURIComponent(playbookMatch[1]);
+        if (playbookId.includes("/")) {
+            const pkgFromRef = playbookId.slice(0, playbookId.lastIndexOf("/"));
+            try {
+                assertPackageAllowed(pkgFromRef, options);
+            }
+            catch (err) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: "PACKAGE_NOT_ALLOWED",
+                        message: err.message || `Package '${pkgFromRef}' is not in the allowed package list`,
+                    },
+                }, 403, corsHeaders);
+            }
+        }
+        try {
+            const pb = await target.describePlaybook(playbookId);
+            const unwrapped = target.unwrap?.();
+            let pkgId = pb.packageId || (unwrapped && "packageId" in unwrapped ? unwrapped.packageId : undefined);
+            if (!pkgId && host) {
+                for (const app of host.listApps()) {
+                    try {
+                        const map = app.getStaticPlaybookMap?.();
+                        const cleanId = playbookId.replace(/\.md$/, "");
+                        if (map?.has(cleanId) || map?.has(playbookId)) {
+                            pkgId = app.packageId;
+                            break;
+                        }
+                    }
+                    catch { }
+                }
+            }
+            if (!pkgId) {
+                const allPbs = await target.listPlaybooks().catch(() => []);
+                const matched = allPbs.find((p) => p.id === playbookId || p.id.endsWith(`/${playbookId}`));
+                if (matched?.packageId) {
+                    pkgId = matched.packageId;
+                }
+            }
+            assertPackageAllowed(pkgId, options);
+            return jsonResponse(pb, 200, corsHeaders);
+        }
+        catch (err) {
+            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: "PACKAGE_NOT_ALLOWED",
+                        message: err.message || "Package is not in the allowed package list",
+                    },
+                }, 403, corsHeaders);
+            }
+            return jsonResponse({ ok: false, error: { code: "PLAYBOOK_NOT_FOUND", message: err.message } }, 404, corsHeaders);
+        }
+    }
+    return null;
+}

package/dist/server/routes/runs.d.ts

@@ -1,5 +1,5 @@
-import { type RouteContext } from "./common";
+import { type RouteContext } from "./common.js";
 /**
- * 处理历史运行记录检索、清理、详情及 SSE 流式日志接口。
+ * 处理历史运行记录查询、清理、详情及 SSE 流式日志接口。
  */
 export declare function handleRunsRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/runs.js

@@ -0,0 +1,343 @@
+import { filterByIntent } from "../../filter/index.js";
+import { EXECUTION_FAILED } from "../../errors.js";
+import { isTerminalRunStatus } from "../../storage/types.js";
+import { readJsonBody } from "../body.js";
+import { getSubPath, jsonResponse } from "./common.js";
+/**
+ * 处理历史运行记录查询、清理、详情及 SSE 流式日志接口。
+ */
+export async function handleRunsRoutes(ctx) {
+    const { req, url, pathname, corsHeaders, options, target, host } = ctx;
+    const subpath = getSubPath(pathname);
+    // 1. Runs List: GET /api/v2/runs, GET /runs
+    if (subpath === "/runs" && req.method === "GET") {
+        try {
+            const status = url.searchParams.get("status") || undefined;
+            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);
+            if (packageId &&
+                options.packageAllowlist &&
+                options.packageAllowlist.length > 0 &&
+                !options.packageAllowlist.includes(packageId)) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        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 {
+                        const records = app.storage.listRuns({ actionId, limit });
+                        for (const r of records) {
+                            if (!seenRunIds.has(r.id)) {
+                                seenRunIds.add(r.id);
+                                if (status && r.status !== status)
+                                    continue;
+                                if (options.packageAllowlist &&
+                                    options.packageAllowlist.length > 0 &&
+                                    r.packageId &&
+                                    !options.packageAllowlist.includes(r.packageId)) {
+                                    continue;
+                                }
+                                allRuns.push(r);
+                            }
+                        }
+                    }
+                    catch { }
+                }
+            }
+            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);
+        }
+        catch (err) {
+            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.
+    if ((subpath === "/runs/clear" && req.method === "POST") ||
+        (subpath === "/runs" && req.method === "DELETE")) {
+        try {
+            let body = {};
+            if (req.method === "POST" || req.headers.get("content-type")?.includes("json")) {
+                body = await readJsonBody(req, { maxBytes: options.maxBodyBytes }).catch(() => ({}));
+            }
+            const packageId = url.searchParams.get("packageId") || body.packageId || undefined;
+            const actionId = url.searchParams.get("actionId") || body.actionId || undefined;
+            const status = url.searchParams.get("status") || body.status || undefined;
+            if (packageId &&
+                options.packageAllowlist &&
+                options.packageAllowlist.length > 0 &&
+                !options.packageAllowlist.includes(packageId)) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        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 });
+                }
+            }
+            return jsonResponse({ ok: true, clearedCount }, 200, corsHeaders);
+        }
+        catch (err) {
+            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);
+        if (!run) {
+            return jsonResponse({ ok: false, error: { code: "RUN_NOT_FOUND", message: `Run '${runId}' not found` } }, 404, corsHeaders);
+        }
+        if (options.packageAllowlist &&
+            options.packageAllowlist.length > 0 &&
+            (!run.packageId || !options.packageAllowlist.includes(run.packageId))) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: "PACKAGE_FORBIDDEN",
+                    message: `Package '${run.packageId}' is not in the allowed package list`,
+                },
+            }, 403, corsHeaders);
+        }
+        // 解析 Last-Event-ID 请求头或 query 参数 after 游标
+        const lastEventIdHeader = req.headers.get("Last-Event-ID") ||
+            req.headers.get("last-event-id") ||
+            url.searchParams.get("after") ||
+            undefined;
+        let afterCursor = undefined;
+        if (lastEventIdHeader !== undefined && lastEventIdHeader.trim() !== "") {
+            const trimmed = lastEventIdHeader.trim();
+            if (/^-?\d+$/.test(trimmed)) {
+                afterCursor = parseInt(trimmed, 10);
+            }
+            else {
+                afterCursor = trimmed;
+            }
+        }
+        const eventStream = target.events(runId, { after: afterCursor, signal: req.signal });
+        const iterator = eventStream[Symbol.asyncIterator]();
+        // 检查游标是否在建流前已过期：拉取首个事件，若抛出 EVENT_CURSOR_EXPIRED 直接返回 410
+        let firstResult;
+        try {
+            firstResult = await iterator.next();
+        }
+        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;
+        }
+        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;
+                        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`));
+                        // 若首条事件为背压终止事件，立即关闭通道
+                        if (evt.type === "error" && evt.error?.code === "EVENT_BACKPRESSURE_LIMIT") {
+                            controller.close();
+                            return;
+                        }
+                    }
+                    // 循环消费后续实时或队列事件
+                    while (!req.signal.aborted) {
+                        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`));
+                        // 若收到背压截断终止事件，正常关闭流通道
+                        if (evt.type === "error" && evt.error?.code === "EVENT_BACKPRESSURE_LIMIT") {
+                            break;
+                        }
+                    }
+                    if (!sawFinish && run && isTerminalRunStatus(run.status)) {
+                        const finishEvt = {
+                            type: "finish",
+                            runId,
+                            timestamp: run.finishedAt || new Date().toISOString(),
+                            result: run.status === "success"
+                                ? { ok: true, runId, data: run.output ?? null }
+                                : {
+                                    ok: false,
+                                    runId,
+                                    error: run.error || {
+                                        code: run.status === "interrupted" ? "RUN_INTERRUPTED" : EXECUTION_FAILED,
+                                        message: `Run finished with status ${run.status}`,
+                                    },
+                                },
+                        };
+                        controller.enqueue(encoder.encode(`event: finish\ndata: ${JSON.stringify(finishEvt)}\n\n`));
+                    }
+                }
+                catch {
+                    // 忽略中断
+                }
+                finally {
+                    try {
+                        controller.close();
+                    }
+                    catch { }
+                }
+            },
+            cancel() { },
+        });
+        return new Response(stream, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                ...corsHeaders,
+            },
+        });
+    }
+    // 4. Run Show: GET /api/v2/runs/:runId, GET /runs/:runId
+    const runShowMatch = subpath.match(/^\/runs\/([^/]+)$/);
+    if (runShowMatch && req.method === "GET") {
+        const runId = decodeURIComponent(runShowMatch[1]);
+        const run = await target.getRun(runId);
+        if (!run) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: "RUN_NOT_FOUND",
+                    message: `Run '${runId}' not found`,
+                },
+            }, 404, corsHeaders);
+        }
+        if (options.packageAllowlist &&
+            options.packageAllowlist.length > 0 &&
+            (!run.packageId || !options.packageAllowlist.includes(run.packageId))) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: "PACKAGE_FORBIDDEN",
+                    message: `Package '${run.packageId || "unknown"}' is not in the allowed package list`,
+                },
+            }, 403, corsHeaders);
+        }
+        return jsonResponse(run, 200, corsHeaders);
+    }
+    // 5. Run Cancel: POST /api/v2/runs/:runId/cancel, POST /runs/:runId/cancel
+    const runCancelMatch = subpath.match(/^\/runs\/([^/]+)\/cancel$/);
+    if (runCancelMatch && req.method === "POST") {
+        const runId = decodeURIComponent(runCancelMatch[1]);
+        if (options.packageAllowlist && options.packageAllowlist.length > 0) {
+            const run = await target.getRun(runId);
+            if (run && (!run.packageId || !options.packageAllowlist.includes(run.packageId))) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: "PACKAGE_FORBIDDEN",
+                        message: `Package '${run.packageId}' is not in the allowed package list`,
+                    },
+                }, 403, corsHeaders);
+            }
+        }
+        let body = {};
+        try {
+            body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
+        }
+        catch { }
+        const reason = body?.reason || "Cancelled by client request";
+        const cancelResult = await target.cancelRun(runId, reason);
+        if (cancelResult.outcome === "not_found") {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: "RUN_NOT_FOUND",
+                    message: `Run '${runId}' not found`,
+                },
+            }, 404, corsHeaders);
+        }
+        if (cancelResult.outcome === "already_terminal") {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: "RUN_ALREADY_FINISHED",
+                    message: `Run '${runId}' has already finished with status '${cancelResult.status}'`,
+                    status: cancelResult.status,
+                },
+            }, 409, corsHeaders);
+        }
+        return jsonResponse({
+            ok: true,
+            runId,
+            status: "cancelled",
+        }, 200, corsHeaders);
+    }
+    return null;
+}

package/dist/server/routes/state.d.ts

@@ -1,5 +1,6 @@
-import { type RouteContext } from "./common";
+import { type RouteContext } from "./common.js";
 /**
  * 处理状态键名列表、读取、写入、删除及清空接口。
+ * 在未显式开启管理功能 (options.enableManagement !== true) 时返回 403 拒绝。
  */
 export declare function handleStateRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/state.js

@@ -0,0 +1,169 @@
+import { decodeStateKey } from "../../storage/index.js";
+import { CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND } from "../../errors.js";
+import { readJsonBody } from "../body.js";
+import { assertPackageAllowed, getSubPath, jsonResponse, resolveAppForPackage } from "./common.js";
+/**
+ * 处理状态键名列表、读取、写入、删除及清空接口。
+ * 在未显式开启管理功能 (options.enableManagement !== true) 时返回 403 拒绝。
+ */
+export async function handleStateRoutes(ctx) {
+    const { req, url, pathname, corsHeaders, options, host, target } = ctx;
+    const subpath = getSubPath(pathname);
+    const isStateRoute = subpath === "/state" ||
+        subpath.startsWith("/state/") ||
+        subpath.startsWith("/management/state");
+    if (!isStateRoute) {
+        return null;
+    }
+    // 校验管理能力开关
+    if (options.enableManagement !== true) {
+        return jsonResponse({
+            ok: false,
+            error: {
+                code: CAPABILITY_UNAVAILABLE,
+                message: "Management APIs are not enabled on this server. Set enableManagement: true to enable.",
+            },
+        }, 403, corsHeaders);
+    }
+    // 1. State List: GET /state
+    if (subpath === "/state" && req.method === "GET") {
+        try {
+            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 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);
+        }
+        catch (err) {
+            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        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);
+        }
+    }
+    // 2. State Clear: POST /state/clear
+    if (subpath === "/state/clear" && req.method === "POST") {
+        try {
+            const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes }).catch(() => ({}));
+            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,
+                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);
+        }
+        catch (err) {
+            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        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);
+        }
+    }
+    // 3. State Key CRUD: GET / PUT / POST / DELETE /state/:key
+    const stateKeyMatch = subpath.match(/^\/state\/([^/]+)$/);
+    if (stateKeyMatch) {
+        try {
+            const key = decodeURIComponent(stateKeyMatch[1]);
+            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);
+            if (req.method === "GET") {
+                const entry = await app.storage.findState(key, effectiveNs);
+                if (!entry || entry.value === undefined) {
+                    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: entry.key,
+                    namespace: entry.namespace,
+                    value: entry.value,
+                    expiresAt: entry.expiresAt,
+                }, 200, corsHeaders);
+            }
+            if (req.method === "PUT" || req.method === "POST") {
+                const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
+                const val = body.value !== undefined ? body.value : body;
+                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) {
+                    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);
+            }
+            if (req.method === "DELETE") {
+                const deleted = await app.storage.deleteStateSmart(key, effectiveNs);
+                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);
+            }
+        }
+        catch (err) {
+            if (err.code === "PACKAGE_NOT_ALLOWED" || err.status === 403) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        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);
+        }
+    }
+    return null;
+}