@undefineds.co/xpod 0.3.58 → 0.3.62

package/dist/document/ReaderPolicy.d.ts

@@ -0,0 +1,89 @@
+export type ReaderDecisionOwner = 'agent' | 'system-prefetch' | 'user';
+export type ReaderExpectedUse = 'structure-probe' | 'answer-evidence' | 'table-extraction' | 'ocr' | 'full-import';
+export type SystemPrefetchTrigger = 'user-open-detail' | 'user-scroll-near-unread-page' | 'user-search-within-document';
+export interface DocumentReaderPolicy {
+    provider: string;
+    model: string;
+    l0: {
+        readExternal: false;
+        decisionOwner: 'agent';
+        allowContextInference: boolean;
+        allowLightweightPreview: boolean;
+        suggestion: {
+            localPreviewPages: number;
+            localPreviewBytes: number;
+        };
+    };
+    decision: {
+        owner: 'agent';
+        defaultSuggestion: {
+            initialPages: number;
+            structureProbeMaxPages: number;
+            pageWindow: number;
+            maxPageWindow: number;
+        };
+        allowAgentOverride: boolean;
+        requireReason: boolean;
+        exposeBudgetToAgent: boolean;
+        overBudgetBehavior: 'ask-user-or-degrade';
+    };
+    systemPrefetch: {
+        owner: 'system';
+        triggers: SystemPrefetchTrigger[];
+        lookAheadPages: number;
+        maxLookAheadPages: number;
+        respectHardLimits: boolean;
+    };
+    hardLimits: {
+        maxPagesPerRun: number;
+        maxPagesPerFilePerDay: number;
+        maxDailyProviderBudgetRatio: number;
+    };
+}
+export interface ReaderUsageSnapshot {
+    runUsedPages: number;
+    fileUsedPagesToday: number;
+    providerUsedPagesToday: number;
+    providerDailyPages?: number;
+}
+export interface ReaderBudgetSnapshot {
+    runRemainingPages: number;
+    fileRemainingPagesToday: number;
+    providerRemainingPagesToday?: number;
+    providerSoftBudgetPagesToday?: number;
+    providerSoftRemainingPagesToday?: number;
+}
+export interface ReaderRequest {
+    owner: ReaderDecisionOwner;
+    source: string;
+    pageRange: string;
+    reason?: string;
+    expectedUse?: ReaderExpectedUse;
+    userConfirmed?: boolean;
+    trigger?: SystemPrefetchTrigger;
+    lookAheadPages?: number;
+}
+export interface ReaderRequestEvaluation {
+    status: 'allow' | 'needs_user_confirmation' | 'deny';
+    pageCount: number;
+    budget: ReaderBudgetSnapshot;
+    reasons: string[];
+}
+export interface SystemPrefetchInput {
+    source: string;
+    trigger: SystemPrefetchTrigger;
+    visiblePage: number;
+    totalPages?: number;
+    readRanges?: string[];
+}
+export interface SystemPrefetchRequest extends ReaderRequest {
+    owner: 'system-prefetch';
+    trigger: SystemPrefetchTrigger;
+    visiblePage: number;
+    lookAheadPages: number;
+}
+export declare const DEFAULT_DOCUMENT_READER_POLICY: DocumentReaderPolicy;
+export declare function countPagesInRange(pageRange: string): number;
+export declare function computeReaderBudget(policy: DocumentReaderPolicy, usage: ReaderUsageSnapshot): ReaderBudgetSnapshot;
+export declare function evaluateReaderRequest(policy: DocumentReaderPolicy, request: ReaderRequest, usage: ReaderUsageSnapshot): ReaderRequestEvaluation;
+export declare function planSystemPrefetch(policy: DocumentReaderPolicy, input: SystemPrefetchInput): SystemPrefetchRequest | undefined;

package/dist/document/ReaderPolicy.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DOCUMENT_READER_POLICY = void 0;
+exports.countPagesInRange = countPagesInRange;
+exports.computeReaderBudget = computeReaderBudget;
+exports.evaluateReaderRequest = evaluateReaderRequest;
+exports.planSystemPrefetch = planSystemPrefetch;
+exports.DEFAULT_DOCUMENT_READER_POLICY = {
+    provider: 'paddleocr',
+    model: 'pp-ocrv6',
+    l0: {
+        readExternal: false,
+        decisionOwner: 'agent',
+        allowContextInference: true,
+        allowLightweightPreview: true,
+        suggestion: {
+            localPreviewPages: 1,
+            localPreviewBytes: 65_536,
+        },
+    },
+    decision: {
+        owner: 'agent',
+        defaultSuggestion: {
+            initialPages: 20,
+            structureProbeMaxPages: 50,
+            pageWindow: 50,
+            maxPageWindow: 100,
+        },
+        allowAgentOverride: true,
+        requireReason: true,
+        exposeBudgetToAgent: true,
+        overBudgetBehavior: 'ask-user-or-degrade',
+    },
+    systemPrefetch: {
+        owner: 'system',
+        triggers: ['user-open-detail', 'user-scroll-near-unread-page', 'user-search-within-document'],
+        lookAheadPages: 10,
+        maxLookAheadPages: 30,
+        respectHardLimits: true,
+    },
+    hardLimits: {
+        maxPagesPerRun: 500,
+        maxPagesPerFilePerDay: 1_000,
+        maxDailyProviderBudgetRatio: 0.8,
+    },
+};
+function countPagesInRange(pageRange) {
+    const ranges = pageRange
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (ranges.length === 0)
+        return 0;
+    let total = 0;
+    for (const range of ranges) {
+        const match = /^(\d+)(?:\s*-\s*(\d+))?$/.exec(range);
+        if (!match)
+            return 0;
+        const start = Number(match[1]);
+        const end = match[2] ? Number(match[2]) : start;
+        if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start) {
+            return 0;
+        }
+        total += end - start + 1;
+    }
+    return total;
+}
+function computeReaderBudget(policy, usage) {
+    const providerRemainingPagesToday = usage.providerDailyPages === undefined
+        ? undefined
+        : Math.max(0, usage.providerDailyPages - usage.providerUsedPagesToday);
+    const providerSoftBudgetPagesToday = usage.providerDailyPages === undefined
+        ? undefined
+        : Math.floor(usage.providerDailyPages * policy.hardLimits.maxDailyProviderBudgetRatio);
+    const providerSoftRemainingPagesToday = providerSoftBudgetPagesToday === undefined
+        ? undefined
+        : Math.max(0, providerSoftBudgetPagesToday - usage.providerUsedPagesToday);
+    return {
+        runRemainingPages: Math.max(0, policy.hardLimits.maxPagesPerRun - usage.runUsedPages),
+        fileRemainingPagesToday: Math.max(0, policy.hardLimits.maxPagesPerFilePerDay - usage.fileUsedPagesToday),
+        providerRemainingPagesToday,
+        providerSoftBudgetPagesToday,
+        providerSoftRemainingPagesToday,
+    };
+}
+function evaluateReaderRequest(policy, request, usage) {
+    const pageCount = countPagesInRange(request.pageRange);
+    const budget = computeReaderBudget(policy, usage);
+    const reasons = [];
+    if (pageCount <= 0)
+        reasons.push('invalid_page_range');
+    if (request.owner === 'agent' && policy.decision.requireReason && !request.reason?.trim()) {
+        reasons.push('agent_reason_required');
+    }
+    if (pageCount > budget.runRemainingPages)
+        reasons.push('run_page_limit_exceeded');
+    if (pageCount > budget.fileRemainingPagesToday)
+        reasons.push('file_daily_page_limit_exceeded');
+    if (budget.providerRemainingPagesToday !== undefined && pageCount > budget.providerRemainingPagesToday) {
+        reasons.push('provider_daily_pages_exhausted');
+    }
+    const hardFailure = reasons.some((reason) => reason !== 'provider_soft_budget_exceeded');
+    if (hardFailure) {
+        return { status: 'deny', pageCount, budget, reasons };
+    }
+    if (request.owner !== 'user'
+        && !request.userConfirmed
+        && budget.providerSoftRemainingPagesToday !== undefined
+        && pageCount > budget.providerSoftRemainingPagesToday) {
+        return {
+            status: 'needs_user_confirmation',
+            pageCount,
+            budget,
+            reasons: ['provider_soft_budget_exceeded'],
+        };
+    }
+    return { status: 'allow', pageCount, budget, reasons };
+}
+function planSystemPrefetch(policy, input) {
+    if (!policy.systemPrefetch.triggers.includes(input.trigger))
+        return undefined;
+    const visiblePage = Math.max(1, Math.floor(input.visiblePage));
+    const lookAheadPages = policy.systemPrefetch.lookAheadPages;
+    const maxEnd = input.totalPages === undefined
+        ? visiblePage + lookAheadPages
+        : Math.min(input.totalPages, visiblePage + lookAheadPages);
+    const firstUnread = firstUnreadPage(visiblePage, maxEnd, input.readRanges ?? []);
+    if (firstUnread === undefined)
+        return undefined;
+    const end = Math.min(maxEnd, firstUnread + lookAheadPages - 1);
+    return {
+        owner: 'system-prefetch',
+        source: input.source,
+        pageRange: `${firstUnread}-${end}`,
+        trigger: input.trigger,
+        visiblePage,
+        lookAheadPages,
+        expectedUse: 'structure-probe',
+    };
+}
+function firstUnreadPage(start, end, readRanges) {
+    for (let page = start; page <= end; page += 1) {
+        if (!isPageCovered(page, readRanges))
+            return page;
+    }
+    return undefined;
+}
+function isPageCovered(page, readRanges) {
+    return readRanges.some((range) => {
+        const match = /^(\d+)(?:\s*-\s*(\d+))?$/.exec(range.trim());
+        if (!match)
+            return false;
+        const start = Number(match[1]);
+        const end = match[2] ? Number(match[2]) : start;
+        return page >= start && page <= end;
+    });
+}
+//# sourceMappingURL=ReaderPolicy.js.map

package/dist/document/ReaderPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReaderPolicy.js","sourceRoot":"","sources":["../../src/document/ReaderPolicy.ts"],"names":[],"mappings":";;;AA8IA,8CAoBC;AAED,kDAkBC;AAED,sDAuCC;AAED,gDAyBC;AApJY,QAAA,8BAA8B,GAAyB;IAClE,QAAQ,EAAE,WAAW;IACrB,KAAK,EAAE,UAAU;IACjB,EAAE,EAAE;QACF,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,OAAO;QACtB,qBAAqB,EAAE,IAAI;QAC3B,uBAAuB,EAAE,IAAI;QAC7B,UAAU,EAAE;YACV,iBAAiB,EAAE,CAAC;YACpB,iBAAiB,EAAE,MAAM;SAC1B;KACF;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,OAAO;QACd,iBAAiB,EAAE;YACjB,YAAY,EAAE,EAAE;YAChB,sBAAsB,EAAE,EAAE;YAC1B,UAAU,EAAE,EAAE;YACd,aAAa,EAAE,GAAG;SACnB;QACD,kBAAkB,EAAE,IAAI;QACxB,aAAa,EAAE,IAAI;QACnB,mBAAmB,EAAE,IAAI;QACzB,kBAAkB,EAAE,qBAAqB;KAC1C;IACD,cAAc,EAAE;QACd,KAAK,EAAE,QAAQ;QACf,QAAQ,EAAE,CAAC,kBAAkB,EAAE,8BAA8B,EAAE,6BAA6B,CAAC;QAC7F,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,IAAI;KACxB;IACD,UAAU,EAAE;QACV,cAAc,EAAE,GAAG;QACnB,qBAAqB,EAAE,KAAK;QAC5B,2BAA2B,EAAE,GAAG;KACjC;CACF,CAAC;AAEF,SAAgB,iBAAiB,CAAC,SAAiB;IACjD,MAAM,MAAM,GAAG,SAAS;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAElC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC;QACrB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;YACnF,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,IAAI,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,mBAAmB,CAAC,MAA4B,EAAE,KAA0B;IAC1F,MAAM,2BAA2B,GAAG,KAAK,CAAC,kBAAkB,KAAK,SAAS;QACxE,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACzE,MAAM,4BAA4B,GAAG,KAAK,CAAC,kBAAkB,KAAK,SAAS;QACzE,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,kBAAkB,GAAG,MAAM,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAC;IACzF,MAAM,+BAA+B,GAAG,4BAA4B,KAAK,SAAS;QAChF,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,4BAA4B,GAAG,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAE7E,OAAO;QACL,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,cAAc,GAAG,KAAK,CAAC,YAAY,CAAC;QACrF,uBAAuB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,qBAAqB,GAAG,KAAK,CAAC,kBAAkB,CAAC;QACxG,2BAA2B;QAC3B,4BAA4B;QAC5B,+BAA+B;KAChC,CAAC;AACJ,CAAC;AAED,SAAgB,qBAAqB,CACnC,MAA4B,EAC5B,OAAsB,EACtB,KAA0B;IAE1B,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACvD,IAAI,OAAO,CAAC,KAAK,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;QAC1F,OAAO,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,SAAS,GAAG,MAAM,CAAC,iBAAiB;QAAE,OAAO,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAClF,IAAI,SAAS,GAAG,MAAM,CAAC,uBAAuB;QAAE,OAAO,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC/F,IAAI,MAAM,CAAC,2BAA2B,KAAK,SAAS,IAAI,SAAS,GAAG,MAAM,CAAC,2BAA2B,EAAE,CAAC;QACvG,OAAO,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,+BAA+B,CAAC,CAAC;IACzF,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACxD,CAAC;IAED,IACE,OAAO,CAAC,KAAK,KAAK,MAAM;WACrB,CAAC,OAAO,CAAC,aAAa;WACtB,MAAM,CAAC,+BAA+B,KAAK,SAAS;WACpD,SAAS,GAAG,MAAM,CAAC,+BAA+B,EACrD,CAAC;QACD,OAAO;YACL,MAAM,EAAE,yBAAyB;YACjC,SAAS;YACT,MAAM;YACN,OAAO,EAAE,CAAC,+BAA+B,CAAC;SAC3C,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACzD,CAAC;AAED,SAAgB,kBAAkB,CAChC,MAA4B,EAC5B,KAA0B;IAE1B,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAE9E,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IAC/D,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC,cAAc,CAAC;IAC5D,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,KAAK,SAAS;QAC3C,CAAC,CAAC,WAAW,GAAG,cAAc;QAC9B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,WAAW,GAAG,cAAc,CAAC,CAAC;IAE7D,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACjF,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,CAAC,CAAC,CAAC;IAC/D,OAAO;QACL,KAAK,EAAE,iBAAiB;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,GAAG,WAAW,IAAI,GAAG,EAAE;QAClC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,WAAW;QACX,cAAc;QACd,WAAW,EAAE,iBAAiB;KAC/B,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAa,EAAE,GAAW,EAAE,UAAoB;IACvE,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,IAAI,IAAI,GAAG,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC;YAAE,OAAO,IAAI,CAAC;IACpD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,aAAa,CAAC,IAAY,EAAE,UAAoB;IACvD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QAC/B,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAChD,OAAO,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["export type ReaderDecisionOwner = 'agent' | 'system-prefetch' | 'user';\n\nexport type ReaderExpectedUse =\n  | 'structure-probe'\n  | 'answer-evidence'\n  | 'table-extraction'\n  | 'ocr'\n  | 'full-import';\n\nexport type SystemPrefetchTrigger =\n  | 'user-open-detail'\n  | 'user-scroll-near-unread-page'\n  | 'user-search-within-document';\n\nexport interface DocumentReaderPolicy {\n  provider: string;\n  model: string;\n  l0: {\n    readExternal: false;\n    decisionOwner: 'agent';\n    allowContextInference: boolean;\n    allowLightweightPreview: boolean;\n    suggestion: {\n      localPreviewPages: number;\n      localPreviewBytes: number;\n    };\n  };\n  decision: {\n    owner: 'agent';\n    defaultSuggestion: {\n      initialPages: number;\n      structureProbeMaxPages: number;\n      pageWindow: number;\n      maxPageWindow: number;\n    };\n    allowAgentOverride: boolean;\n    requireReason: boolean;\n    exposeBudgetToAgent: boolean;\n    overBudgetBehavior: 'ask-user-or-degrade';\n  };\n  systemPrefetch: {\n    owner: 'system';\n    triggers: SystemPrefetchTrigger[];\n    lookAheadPages: number;\n    maxLookAheadPages: number;\n    respectHardLimits: boolean;\n  };\n  hardLimits: {\n    maxPagesPerRun: number;\n    maxPagesPerFilePerDay: number;\n    maxDailyProviderBudgetRatio: number;\n  };\n}\n\nexport interface ReaderUsageSnapshot {\n  runUsedPages: number;\n  fileUsedPagesToday: number;\n  providerUsedPagesToday: number;\n  providerDailyPages?: number;\n}\n\nexport interface ReaderBudgetSnapshot {\n  runRemainingPages: number;\n  fileRemainingPagesToday: number;\n  providerRemainingPagesToday?: number;\n  providerSoftBudgetPagesToday?: number;\n  providerSoftRemainingPagesToday?: number;\n}\n\nexport interface ReaderRequest {\n  owner: ReaderDecisionOwner;\n  source: string;\n  pageRange: string;\n  reason?: string;\n  expectedUse?: ReaderExpectedUse;\n  userConfirmed?: boolean;\n  trigger?: SystemPrefetchTrigger;\n  lookAheadPages?: number;\n}\n\nexport interface ReaderRequestEvaluation {\n  status: 'allow' | 'needs_user_confirmation' | 'deny';\n  pageCount: number;\n  budget: ReaderBudgetSnapshot;\n  reasons: string[];\n}\n\nexport interface SystemPrefetchInput {\n  source: string;\n  trigger: SystemPrefetchTrigger;\n  visiblePage: number;\n  totalPages?: number;\n  readRanges?: string[];\n}\n\nexport interface SystemPrefetchRequest extends ReaderRequest {\n  owner: 'system-prefetch';\n  trigger: SystemPrefetchTrigger;\n  visiblePage: number;\n  lookAheadPages: number;\n}\n\nexport const DEFAULT_DOCUMENT_READER_POLICY: DocumentReaderPolicy = {\n  provider: 'paddleocr',\n  model: 'pp-ocrv6',\n  l0: {\n    readExternal: false,\n    decisionOwner: 'agent',\n    allowContextInference: true,\n    allowLightweightPreview: true,\n    suggestion: {\n      localPreviewPages: 1,\n      localPreviewBytes: 65_536,\n    },\n  },\n  decision: {\n    owner: 'agent',\n    defaultSuggestion: {\n      initialPages: 20,\n      structureProbeMaxPages: 50,\n      pageWindow: 50,\n      maxPageWindow: 100,\n    },\n    allowAgentOverride: true,\n    requireReason: true,\n    exposeBudgetToAgent: true,\n    overBudgetBehavior: 'ask-user-or-degrade',\n  },\n  systemPrefetch: {\n    owner: 'system',\n    triggers: ['user-open-detail', 'user-scroll-near-unread-page', 'user-search-within-document'],\n    lookAheadPages: 10,\n    maxLookAheadPages: 30,\n    respectHardLimits: true,\n  },\n  hardLimits: {\n    maxPagesPerRun: 500,\n    maxPagesPerFilePerDay: 1_000,\n    maxDailyProviderBudgetRatio: 0.8,\n  },\n};\n\nexport function countPagesInRange(pageRange: string): number {\n  const ranges = pageRange\n    .split(',')\n    .map((part) => part.trim())\n    .filter(Boolean);\n\n  if (ranges.length === 0) return 0;\n\n  let total = 0;\n  for (const range of ranges) {\n    const match = /^(\\d+)(?:\\s*-\\s*(\\d+))?$/.exec(range);\n    if (!match) return 0;\n    const start = Number(match[1]);\n    const end = match[2] ? Number(match[2]) : start;\n    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start) {\n      return 0;\n    }\n    total += end - start + 1;\n  }\n  return total;\n}\n\nexport function computeReaderBudget(policy: DocumentReaderPolicy, usage: ReaderUsageSnapshot): ReaderBudgetSnapshot {\n  const providerRemainingPagesToday = usage.providerDailyPages === undefined\n    ? undefined\n    : Math.max(0, usage.providerDailyPages - usage.providerUsedPagesToday);\n  const providerSoftBudgetPagesToday = usage.providerDailyPages === undefined\n    ? undefined\n    : Math.floor(usage.providerDailyPages * policy.hardLimits.maxDailyProviderBudgetRatio);\n  const providerSoftRemainingPagesToday = providerSoftBudgetPagesToday === undefined\n    ? undefined\n    : Math.max(0, providerSoftBudgetPagesToday - usage.providerUsedPagesToday);\n\n  return {\n    runRemainingPages: Math.max(0, policy.hardLimits.maxPagesPerRun - usage.runUsedPages),\n    fileRemainingPagesToday: Math.max(0, policy.hardLimits.maxPagesPerFilePerDay - usage.fileUsedPagesToday),\n    providerRemainingPagesToday,\n    providerSoftBudgetPagesToday,\n    providerSoftRemainingPagesToday,\n  };\n}\n\nexport function evaluateReaderRequest(\n  policy: DocumentReaderPolicy,\n  request: ReaderRequest,\n  usage: ReaderUsageSnapshot,\n): ReaderRequestEvaluation {\n  const pageCount = countPagesInRange(request.pageRange);\n  const budget = computeReaderBudget(policy, usage);\n  const reasons: string[] = [];\n\n  if (pageCount <= 0) reasons.push('invalid_page_range');\n  if (request.owner === 'agent' && policy.decision.requireReason && !request.reason?.trim()) {\n    reasons.push('agent_reason_required');\n  }\n  if (pageCount > budget.runRemainingPages) reasons.push('run_page_limit_exceeded');\n  if (pageCount > budget.fileRemainingPagesToday) reasons.push('file_daily_page_limit_exceeded');\n  if (budget.providerRemainingPagesToday !== undefined && pageCount > budget.providerRemainingPagesToday) {\n    reasons.push('provider_daily_pages_exhausted');\n  }\n\n  const hardFailure = reasons.some((reason) => reason !== 'provider_soft_budget_exceeded');\n  if (hardFailure) {\n    return { status: 'deny', pageCount, budget, reasons };\n  }\n\n  if (\n    request.owner !== 'user'\n    && !request.userConfirmed\n    && budget.providerSoftRemainingPagesToday !== undefined\n    && pageCount > budget.providerSoftRemainingPagesToday\n  ) {\n    return {\n      status: 'needs_user_confirmation',\n      pageCount,\n      budget,\n      reasons: ['provider_soft_budget_exceeded'],\n    };\n  }\n\n  return { status: 'allow', pageCount, budget, reasons };\n}\n\nexport function planSystemPrefetch(\n  policy: DocumentReaderPolicy,\n  input: SystemPrefetchInput,\n): SystemPrefetchRequest | undefined {\n  if (!policy.systemPrefetch.triggers.includes(input.trigger)) return undefined;\n\n  const visiblePage = Math.max(1, Math.floor(input.visiblePage));\n  const lookAheadPages = policy.systemPrefetch.lookAheadPages;\n  const maxEnd = input.totalPages === undefined\n    ? visiblePage + lookAheadPages\n    : Math.min(input.totalPages, visiblePage + lookAheadPages);\n\n  const firstUnread = firstUnreadPage(visiblePage, maxEnd, input.readRanges ?? []);\n  if (firstUnread === undefined) return undefined;\n\n  const end = Math.min(maxEnd, firstUnread + lookAheadPages - 1);\n  return {\n    owner: 'system-prefetch',\n    source: input.source,\n    pageRange: `${firstUnread}-${end}`,\n    trigger: input.trigger,\n    visiblePage,\n    lookAheadPages,\n    expectedUse: 'structure-probe',\n  };\n}\n\nfunction firstUnreadPage(start: number, end: number, readRanges: string[]): number | undefined {\n  for (let page = start; page <= end; page += 1) {\n    if (!isPageCovered(page, readRanges)) return page;\n  }\n  return undefined;\n}\n\nfunction isPageCovered(page: number, readRanges: string[]): boolean {\n  return readRanges.some((range) => {\n    const match = /^(\\d+)(?:\\s*-\\s*(\\d+))?$/.exec(range.trim());\n    if (!match) return false;\n    const start = Number(match[1]);\n    const end = match[2] ? Number(match[2]) : start;\n    return page >= start && page <= end;\n  });\n}\n"]}

package/dist/document/ReaderPolicy.jsonld

@@ -0,0 +1,218 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/document/ReaderPolicy.jsonld#DocumentReaderPolicy",
+      "@type": "AbstractClass",
+      "requireElement": "DocumentReaderPolicy",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#DocumentReaderPolicy__member_provider",
+          "memberFieldName": "provider"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#DocumentReaderPolicy__member_model",
+          "memberFieldName": "model"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#DocumentReaderPolicy__member_l0",
+          "memberFieldName": "l0"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#DocumentReaderPolicy__member_decision",
+          "memberFieldName": "decision"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#DocumentReaderPolicy__member_systemPrefetch",
+          "memberFieldName": "systemPrefetch"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#DocumentReaderPolicy__member_hardLimits",
+          "memberFieldName": "hardLimits"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderUsageSnapshot",
+      "@type": "AbstractClass",
+      "requireElement": "ReaderUsageSnapshot",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderUsageSnapshot__member_runUsedPages",
+          "memberFieldName": "runUsedPages"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderUsageSnapshot__member_fileUsedPagesToday",
+          "memberFieldName": "fileUsedPagesToday"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderUsageSnapshot__member_providerUsedPagesToday",
+          "memberFieldName": "providerUsedPagesToday"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderUsageSnapshot__member_providerDailyPages",
+          "memberFieldName": "providerDailyPages"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderBudgetSnapshot",
+      "@type": "AbstractClass",
+      "requireElement": "ReaderBudgetSnapshot",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderBudgetSnapshot__member_runRemainingPages",
+          "memberFieldName": "runRemainingPages"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderBudgetSnapshot__member_fileRemainingPagesToday",
+          "memberFieldName": "fileRemainingPagesToday"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderBudgetSnapshot__member_providerRemainingPagesToday",
+          "memberFieldName": "providerRemainingPagesToday"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderBudgetSnapshot__member_providerSoftBudgetPagesToday",
+          "memberFieldName": "providerSoftBudgetPagesToday"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderBudgetSnapshot__member_providerSoftRemainingPagesToday",
+          "memberFieldName": "providerSoftRemainingPagesToday"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest",
+      "@type": "AbstractClass",
+      "requireElement": "ReaderRequest",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_owner",
+          "memberFieldName": "owner"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_pageRange",
+          "memberFieldName": "pageRange"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_reason",
+          "memberFieldName": "reason"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_expectedUse",
+          "memberFieldName": "expectedUse"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_userConfirmed",
+          "memberFieldName": "userConfirmed"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_trigger",
+          "memberFieldName": "trigger"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest__member_lookAheadPages",
+          "memberFieldName": "lookAheadPages"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequestEvaluation",
+      "@type": "AbstractClass",
+      "requireElement": "ReaderRequestEvaluation",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequestEvaluation__member_status",
+          "memberFieldName": "status"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequestEvaluation__member_pageCount",
+          "memberFieldName": "pageCount"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequestEvaluation__member_budget",
+          "memberFieldName": "budget"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequestEvaluation__member_reasons",
+          "memberFieldName": "reasons"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchInput",
+      "@type": "AbstractClass",
+      "requireElement": "SystemPrefetchInput",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchInput__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchInput__member_trigger",
+          "memberFieldName": "trigger"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchInput__member_visiblePage",
+          "memberFieldName": "visiblePage"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchInput__member_totalPages",
+          "memberFieldName": "totalPages"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchInput__member_readRanges",
+          "memberFieldName": "readRanges"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchRequest",
+      "@type": "AbstractClass",
+      "requireElement": "SystemPrefetchRequest",
+      "extends": [
+        "undefineds:dist/document/ReaderPolicy.jsonld#ReaderRequest"
+      ],
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchRequest__member_owner",
+          "memberFieldName": "owner"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchRequest__member_trigger",
+          "memberFieldName": "trigger"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchRequest__member_visiblePage",
+          "memberFieldName": "visiblePage"
+        },
+        {
+          "@id": "undefineds:dist/document/ReaderPolicy.jsonld#SystemPrefetchRequest__member_lookAheadPages",
+          "memberFieldName": "lookAheadPages"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

package/dist/document/index.d.ts

@@ -1,7 +1,11 @@
 /**
  * Document module - 文档解析和分块
  */
-export * from './DocumentParser';
+export * from './DocumentReader';
 export * from './Chunker';
-export * from './JinaDocumentParser';
+export * from './JinaReader';
 export * from './HeadingChunker';
+export * from './ReaderPolicy';
+export * from './ReaderAiConfig';
+export * from './L0SourceSummary';
+export * from './PaddleOcrReader';

package/dist/document/index.js

@@ -18,9 +18,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 // 接口
-__exportStar(require("./DocumentParser"), exports);
+__exportStar(require("./DocumentReader"), exports);
 __exportStar(require("./Chunker"), exports);
 // 实现
-__exportStar(require("./JinaDocumentParser"), exports);
+__exportStar(require("./JinaReader"), exports);
 __exportStar(require("./HeadingChunker"), exports);
+__exportStar(require("./ReaderPolicy"), exports);
+__exportStar(require("./ReaderAiConfig"), exports);
+__exportStar(require("./L0SourceSummary"), exports);
+__exportStar(require("./PaddleOcrReader"), exports);
 //# sourceMappingURL=index.js.map

package/dist/document/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/document/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,KAAK;AACL,mDAAiC;AACjC,4CAA0B;AAE1B,KAAK;AACL,uDAAqC;AACrC,mDAAiC","sourcesContent":["/**\n * Document module - 文档解析和分块\n */\n\n// 接口\nexport * from './DocumentParser';\nexport * from './Chunker';\n\n// 实现\nexport * from './JinaDocumentParser';\nexport * from './HeadingChunker';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/document/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,KAAK;AACL,mDAAiC;AACjC,4CAA0B;AAE1B,KAAK;AACL,+CAA6B;AAC7B,mDAAiC;AACjC,iDAA+B;AAC/B,mDAAiC;AACjC,oDAAkC;AAClC,oDAAkC","sourcesContent":["/**\n * Document module - 文档解析和分块\n */\n\n// 接口\nexport * from './DocumentReader';\nexport * from './Chunker';\n\n// 实现\nexport * from './JinaReader';\nexport * from './HeadingChunker';\nexport * from './ReaderPolicy';\nexport * from './ReaderAiConfig';\nexport * from './L0SourceSummary';\nexport * from './PaddleOcrReader';\n"]}

package/dist/edge/DdnsManager.d.ts

@@ -17,7 +17,7 @@ export interface DdnsManagerOptions {
     localPort?: number;
     intervalMs?: number;
     autoAllocate?: boolean;
-    tunnelProvider?: 'cloudflare' | 'sakura_frp' | 'ngrok' | 'none';
+    tunnelProvider?: 'cloudflare' | 'sakura_frp' | 'ngrok' | 'frp' | 'none';
 }
 export declare class DdnsManager {
     private readonly logger;

package/dist/edge/DdnsManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"DdnsManager.js","sourceRoot":"","sources":["../../src/edge/DdnsManager.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DDNS Manager for Local Managed Mode\n *\n * Responsibilities (Local managed mode):\n * - Allocate a managed domain on Cloud (subdomain -> fqdn)\n * - Keep the record updated when network changes\n *\n * Note: if the machine has no public IP, we assume tunnel mode and let Cloud\n * point the managed domain to the configured tunnel provider.\n */\n\nimport { getLoggerFor } from 'global-logger-factory';\nimport type { SubdomainClient } from '../subdomain/SubdomainClient';\nimport type { EdgeNodeCapabilityDetector } from './EdgeNodeCapabilityDetector';\n\nexport interface DdnsManagerOptions {\n  client: SubdomainClient;\n  detector: EdgeNodeCapabilityDetector;\n  subdomain: string;\n  localPort?: number;\n  intervalMs?: number;\n  autoAllocate?: boolean;\n\n  // Local tunnel provider preference (best-effort hint for Cloud).\n  tunnelProvider?: 'cloudflare' | 'sakura_frp' | 'ngrok' | 'none';\n}\n\nexport class DdnsManager {\n  private readonly logger = getLoggerFor(this);\n  private readonly client: SubdomainClient;\n  private readonly detector: EdgeNodeCapabilityDetector;\n  private readonly subdomain: string;\n  private readonly localPort?: number;\n  private readonly intervalMs: number;\n  private readonly autoAllocate: boolean;\n  private readonly tunnelProvider: 'cloudflare' | 'sakura_frp' | 'ngrok' | 'none';\n\n  private interval?: NodeJS.Timeout;\n  private allocated = false;\n  private fqdn?: string;\n  private lastIpv4?: string;\n  private lastIpv6?: string;\n  private lastMode: 'direct' | 'tunnel' | 'unknown' = 'unknown';\n\n  public constructor(options: DdnsManagerOptions) {\n    this.client = options.client;\n    this.detector = options.detector;\n    this.subdomain = options.subdomain;\n    this.localPort = options.localPort;\n    this.intervalMs = options.intervalMs ?? 60_000;\n    this.autoAllocate = options.autoAllocate ?? true;\n    this.tunnelProvider = options.tunnelProvider ?? 'none';\n  }\n\n  public async start(): Promise<void> {\n    if (this.interval) {\n      return;\n    }\n\n    this.logger.info(`Starting DDNS manager for subdomain: ${this.subdomain}`);\n\n    await this.runCycle();\n    this.interval = setInterval(() => void this.runCycle(), this.intervalMs);\n  }\n\n  public stop(): void {\n    if (this.interval) {\n      clearInterval(this.interval);\n      this.interval = undefined;\n    }\n    this.logger.info('DDNS manager stopped');\n  }\n\n  public getFqdn(): string | undefined {\n    return this.allocated ? this.fqdn : undefined;\n  }\n\n  public isAllocated(): boolean {\n    return this.allocated;\n  }\n\n  public getStatus(): {\n    allocated: boolean;\n    fqdn?: string;\n    ipv4?: string;\n    ipv6?: string;\n    mode: 'direct' | 'tunnel' | 'unknown';\n    tunnelProvider: string;\n  } {\n    return {\n      allocated: this.allocated,\n      fqdn: this.fqdn,\n      ipv4: this.lastIpv4,\n      ipv6: this.lastIpv6,\n      mode: this.lastMode,\n      tunnelProvider: this.tunnelProvider,\n    };\n  }\n\n  public async runOnce(): Promise<void> {\n    await this.runCycle();\n  }\n\n  private async runCycle(): Promise<void> {\n    try {\n      const netInfo = await this.detector.detectNetworkAddresses();\n\n      const ipv4Public = netInfo.ipv4Public;\n      const ipv6Public = netInfo.ipv6Public;\n      const hasPublicIp = Boolean(ipv4Public || ipv6Public);\n\n      this.lastMode = hasPublicIp ? 'direct' : 'tunnel';\n\n      const ipv4 = ipv4Public ?? netInfo.ipv4;\n      const ipv6 = ipv6Public ?? netInfo.ipv6;\n\n      if (!this.allocated && this.autoAllocate) {\n        await this.allocateSubdomain(ipv4, ipv6);\n      }\n\n      if (this.allocated) {\n        const ipChanged = ipv4 !== this.lastIpv4 || ipv6 !== this.lastIpv6;\n        if (ipChanged || this.lastMode === 'tunnel') {\n          await this.updateDdns(ipv4, ipv6);\n        }\n      }\n    } catch (error: unknown) {\n      this.logger.error(`DDNS cycle failed: ${(error as Error).message}`);\n    }\n  }\n\n  private async allocateSubdomain(ipv4?: string, ipv6?: string): Promise<void> {\n    const existing = await this.client.getDdns(this.subdomain);\n    if (existing) {\n      this.logger.info(`DDNS subdomain already allocated: ${existing.fqdn}`);\n      this.allocated = true;\n      this.fqdn = existing.fqdn;\n      this.lastIpv4 = existing.ipAddress;\n      this.lastIpv6 = existing.ipv6Address;\n      return;\n    }\n\n    this.logger.info(`Allocating DDNS subdomain: ${this.subdomain}`);\n\n    const result = await this.client.allocateDdns({\n      subdomain: this.subdomain,\n      ipAddress: this.lastMode === 'direct' ? ipv4 : undefined,\n      ipv6Address: this.lastMode === 'direct' ? ipv6 : undefined,\n      mode: this.lastMode === 'tunnel' ? 'tunnel' : 'direct',\n      tunnelProvider: this.tunnelProvider,\n      localPort: this.localPort,\n    });\n\n    if (result.success) {\n      this.logger.info(`DDNS allocated: ${result.fqdn}`);\n      this.allocated = true;\n      this.fqdn = result.fqdn;\n      this.lastIpv4 = this.lastMode === 'direct' ? ipv4 : undefined;\n      this.lastIpv6 = this.lastMode === 'direct' ? ipv6 : undefined;\n    }\n  }\n\n  private async updateDdns(ipv4?: string, ipv6?: string): Promise<void> {\n    if (this.lastMode === 'direct' && !ipv4 && !ipv6) {\n      this.logger.debug('No IP address to update in direct mode');\n      return;\n    }\n\n\n    this.logger.info(\n      `Updating DDNS: ${this.subdomain} mode=${this.lastMode} ipv4=${ipv4 ?? 'none'} ipv6=${ipv6 ?? 'none'} tunnel=${this.tunnelProvider}`,\n    );\n\n    const result = await this.client.updateDdns(this.subdomain, {\n      ipAddress: this.lastMode === 'direct' ? ipv4 : undefined,\n      ipv6Address: this.lastMode === 'direct' ? ipv6 : undefined,\n      mode: this.lastMode === 'tunnel' ? 'tunnel' : 'direct',\n      tunnelProvider: this.tunnelProvider,\n      localPort: this.localPort,\n    });\n\n    if (result.success) {\n      this.fqdn = result.fqdn;\n      this.lastIpv4 = this.lastMode === 'direct' ? ipv4 : undefined;\n      this.lastIpv6 = this.lastMode === 'direct' ? ipv6 : undefined;\n      this.logger.info(`DDNS updated: ${result.fqdn}`);\n    }\n  }\n}\n"]}
+{"version":3,"file":"DdnsManager.js","sourceRoot":"","sources":["../../src/edge/DdnsManager.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DDNS Manager for Local Managed Mode\n *\n * Responsibilities (Local managed mode):\n * - Allocate a managed domain on Cloud (subdomain -> fqdn)\n * - Keep the record updated when network changes\n *\n * Note: if the machine has no public IP, we assume tunnel mode and let Cloud\n * point the managed domain to the configured tunnel provider.\n */\n\nimport { getLoggerFor } from 'global-logger-factory';\nimport type { SubdomainClient } from '../subdomain/SubdomainClient';\nimport type { EdgeNodeCapabilityDetector } from './EdgeNodeCapabilityDetector';\n\nexport interface DdnsManagerOptions {\n  client: SubdomainClient;\n  detector: EdgeNodeCapabilityDetector;\n  subdomain: string;\n  localPort?: number;\n  intervalMs?: number;\n  autoAllocate?: boolean;\n\n  // Local tunnel provider preference (best-effort hint for Cloud).\n  tunnelProvider?: 'cloudflare' | 'sakura_frp' | 'ngrok' | 'frp' | 'none';\n}\n\nexport class DdnsManager {\n  private readonly logger = getLoggerFor(this);\n  private readonly client: SubdomainClient;\n  private readonly detector: EdgeNodeCapabilityDetector;\n  private readonly subdomain: string;\n  private readonly localPort?: number;\n  private readonly intervalMs: number;\n  private readonly autoAllocate: boolean;\n  private readonly tunnelProvider: 'cloudflare' | 'sakura_frp' | 'ngrok' | 'frp' | 'none';\n\n  private interval?: NodeJS.Timeout;\n  private allocated = false;\n  private fqdn?: string;\n  private lastIpv4?: string;\n  private lastIpv6?: string;\n  private lastMode: 'direct' | 'tunnel' | 'unknown' = 'unknown';\n\n  public constructor(options: DdnsManagerOptions) {\n    this.client = options.client;\n    this.detector = options.detector;\n    this.subdomain = options.subdomain;\n    this.localPort = options.localPort;\n    this.intervalMs = options.intervalMs ?? 60_000;\n    this.autoAllocate = options.autoAllocate ?? true;\n    this.tunnelProvider = options.tunnelProvider ?? 'none';\n  }\n\n  public async start(): Promise<void> {\n    if (this.interval) {\n      return;\n    }\n\n    this.logger.info(`Starting DDNS manager for subdomain: ${this.subdomain}`);\n\n    await this.runCycle();\n    this.interval = setInterval(() => void this.runCycle(), this.intervalMs);\n  }\n\n  public stop(): void {\n    if (this.interval) {\n      clearInterval(this.interval);\n      this.interval = undefined;\n    }\n    this.logger.info('DDNS manager stopped');\n  }\n\n  public getFqdn(): string | undefined {\n    return this.allocated ? this.fqdn : undefined;\n  }\n\n  public isAllocated(): boolean {\n    return this.allocated;\n  }\n\n  public getStatus(): {\n    allocated: boolean;\n    fqdn?: string;\n    ipv4?: string;\n    ipv6?: string;\n    mode: 'direct' | 'tunnel' | 'unknown';\n    tunnelProvider: string;\n  } {\n    return {\n      allocated: this.allocated,\n      fqdn: this.fqdn,\n      ipv4: this.lastIpv4,\n      ipv6: this.lastIpv6,\n      mode: this.lastMode,\n      tunnelProvider: this.tunnelProvider,\n    };\n  }\n\n  public async runOnce(): Promise<void> {\n    await this.runCycle();\n  }\n\n  private async runCycle(): Promise<void> {\n    try {\n      const netInfo = await this.detector.detectNetworkAddresses();\n\n      const ipv4Public = netInfo.ipv4Public;\n      const ipv6Public = netInfo.ipv6Public;\n      const hasPublicIp = Boolean(ipv4Public || ipv6Public);\n\n      this.lastMode = hasPublicIp ? 'direct' : 'tunnel';\n\n      const ipv4 = ipv4Public ?? netInfo.ipv4;\n      const ipv6 = ipv6Public ?? netInfo.ipv6;\n\n      if (!this.allocated && this.autoAllocate) {\n        await this.allocateSubdomain(ipv4, ipv6);\n      }\n\n      if (this.allocated) {\n        const ipChanged = ipv4 !== this.lastIpv4 || ipv6 !== this.lastIpv6;\n        if (ipChanged || this.lastMode === 'tunnel') {\n          await this.updateDdns(ipv4, ipv6);\n        }\n      }\n    } catch (error: unknown) {\n      this.logger.error(`DDNS cycle failed: ${(error as Error).message}`);\n    }\n  }\n\n  private async allocateSubdomain(ipv4?: string, ipv6?: string): Promise<void> {\n    const existing = await this.client.getDdns(this.subdomain);\n    if (existing) {\n      this.logger.info(`DDNS subdomain already allocated: ${existing.fqdn}`);\n      this.allocated = true;\n      this.fqdn = existing.fqdn;\n      this.lastIpv4 = existing.ipAddress;\n      this.lastIpv6 = existing.ipv6Address;\n      return;\n    }\n\n    this.logger.info(`Allocating DDNS subdomain: ${this.subdomain}`);\n\n    const result = await this.client.allocateDdns({\n      subdomain: this.subdomain,\n      ipAddress: this.lastMode === 'direct' ? ipv4 : undefined,\n      ipv6Address: this.lastMode === 'direct' ? ipv6 : undefined,\n      mode: this.lastMode === 'tunnel' ? 'tunnel' : 'direct',\n      tunnelProvider: this.tunnelProvider,\n      localPort: this.localPort,\n    });\n\n    if (result.success) {\n      this.logger.info(`DDNS allocated: ${result.fqdn}`);\n      this.allocated = true;\n      this.fqdn = result.fqdn;\n      this.lastIpv4 = this.lastMode === 'direct' ? ipv4 : undefined;\n      this.lastIpv6 = this.lastMode === 'direct' ? ipv6 : undefined;\n    }\n  }\n\n  private async updateDdns(ipv4?: string, ipv6?: string): Promise<void> {\n    if (this.lastMode === 'direct' && !ipv4 && !ipv6) {\n      this.logger.debug('No IP address to update in direct mode');\n      return;\n    }\n\n\n    this.logger.info(\n      `Updating DDNS: ${this.subdomain} mode=${this.lastMode} ipv4=${ipv4 ?? 'none'} ipv6=${ipv6 ?? 'none'} tunnel=${this.tunnelProvider}`,\n    );\n\n    const result = await this.client.updateDdns(this.subdomain, {\n      ipAddress: this.lastMode === 'direct' ? ipv4 : undefined,\n      ipv6Address: this.lastMode === 'direct' ? ipv6 : undefined,\n      mode: this.lastMode === 'tunnel' ? 'tunnel' : 'direct',\n      tunnelProvider: this.tunnelProvider,\n      localPort: this.localPort,\n    });\n\n    if (result.success) {\n      this.fqdn = result.fqdn;\n      this.lastIpv4 = this.lastMode === 'direct' ? ipv4 : undefined;\n      this.lastIpv6 = this.lastMode === 'direct' ? ipv6 : undefined;\n      this.logger.info(`DDNS updated: ${result.fqdn}`);\n    }\n  }\n}\n"]}

package/dist/edge/EdgeNodeAgent.d.ts

@@ -1,3 +1,5 @@
+import { AcmeCertificateManager } from './acme/AcmeCertificateManager';
+import { ClusterCertificateManager } from './acme/ClusterCertificateManager';
 import { type P2PSignalingClient, type RawTcpP2PConnectSocket, type RawTcpP2PSleep } from './reachability';
 export interface EdgeNodeP2PAcceptEvent {
     sessionId: string;
@@ -62,6 +64,7 @@ export declare class EdgeNodeAgent {
     private readonly logger;
     private heartbeat?;
     private frpManager?;
+    private localCertificate?;
     private clusterCertificate?;
     private networkDetector?;
     private cachedNetworkInfo?;
@@ -74,6 +77,7 @@ export declare class EdgeNodeAgent {
     private readonly networkDetectionIntervalMs;
     start(options: EdgeNodeAgentOptions): Promise<void>;
     stop(): void;
+    getCertificateRuntime(): AcmeCertificateManager | ClusterCertificateManager | undefined;
     private startP2PAcceptLoop;
     private acceptP2PConnectionOnce;
     private skipAcceptedP2PSessions;

package/dist/edge/EdgeNodeAgent.js

@@ -103,6 +103,11 @@ class EdgeNodeAgent {
         this.p2pAcceptRunning = false;
         void this.frpManager?.stop();
         this.clusterCertificate?.stop();
+        this.localCertificate = undefined;
+        this.clusterCertificate = undefined;
+    }
+    getCertificateRuntime() {
+        return this.clusterCertificate ?? this.localCertificate;
     }
     startP2PAcceptLoop(options) {
         const p2p = options.p2p;
@@ -332,6 +337,7 @@ class EdgeNodeAgent {
             renewBeforeDays: acmeOptions.renewBeforeDays,
             propagationDelayMs: acmeOptions.propagationDelayMs,
         });
+        this.localCertificate = manager;
         try {
             const issued = await manager.ensureCertificate();
             if (issued && acmeOptions.postDeployCommand && acmeOptions.postDeployCommand.length > 0) {