@mebular/fleet 0.0.0-stage → 0.1.0

package/dist/runtime/agent.d.ts

@@ -0,0 +1,100 @@
+import type { TaskState } from '../model.js';
+import type { ExecutionOutcome, TaskExecutor } from './executor.js';
+/** 按 agent 名字选择执行器；**未知 agent 返回 null**（调用方须显式失败，不得静默回退）。 */
+export declare class ExecutorRegistry {
+    private readonly exact;
+    private wildcard;
+    /** 注册某 agent 名；`'*'` 为通配（仅匹配 `to.agent === '*'`）。 */
+    register(agent: string, executor: TaskExecutor): this;
+    resolve(agent: string): TaskExecutor | null;
+    has(agent: string): boolean;
+    names(): string[];
+}
+/** UTF-8 安全截断（按字节），附截断标记。 */
+export declare function truncateOutput(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+    totalBytes: number;
+};
+export interface SpawnResult {
+    code: number | null;
+    /** 已捕获的 stdout（至多 `maxOutputBytes` 字节） */
+    stdout: string;
+    /** stdout 的**总字节数**（含未捕获部分） */
+    stdoutBytes: number;
+    stderrTail: string;
+    timedOut: boolean;
+}
+/**
+ * 允许透传给被派发 Agent 的环境变量**白名单**（非私密运行所需）。
+ * 其余（尤其凭据/令牌）**一律不继承**——daemon 的 env 不外流。
+ */
+export declare const ENV_ALLOWLIST: readonly string[];
+/** 按白名单构建子进程 env；`extra`（调用方显式给出）覆盖白名单同名项。 */
+export declare function buildChildEnv(extra?: Readonly<Record<string, string>>, source?: NodeJS.ProcessEnv): Record<string, string>;
+/** 以参数数组执行命令；捕获 stdout/stderr（stderr 保留尾部）；超时 kill。 */
+export declare function runOnce(options: {
+    command: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+    timeoutMs: number;
+    maxOutputBytes: number;
+}): Promise<SpawnResult>;
+export interface CommandAgentOptions {
+    /** 可执行文件（不经 shell） */
+    command: string;
+    /** 命令后、prompt 参数前的固定参数 */
+    baseArgs?: readonly string[];
+    /** 由任务生成 prompt 相关参数（默认 `['-z', task.intent]`） */
+    promptArgs?: (task: TaskState) => string[];
+    cwd?: string;
+    /** 额外环境变量（值不会被打印/落盘） */
+    env?: Readonly<Record<string, string>>;
+    /** 超时（默认 60000ms） */
+    timeoutMs?: number;
+    /** stdout 截断上限字节（默认 65536） */
+    maxOutputBytes?: number;
+    /** 并发上限（默认 1） */
+    concurrency?: number;
+    /** 结果引用生成（默认：截断后的 stdout） */
+    resultRef?: (stdout: string, task: TaskState) => string;
+}
+/** 通用「命令行 Agent」执行器。 */
+export declare class CommandAgent implements TaskExecutor {
+    private readonly options;
+    private readonly sem;
+    constructor(options: CommandAgentOptions);
+    execute(task: TaskState): Promise<ExecutionOutcome>;
+}
+export interface HermesAgentOptions {
+    /** hermes 可执行文件（默认 `hermes`） */
+    hermesPath?: string;
+    /** 命令后、hermes 参数前的固定参数（测试注入用；生产留空） */
+    commandArgs?: readonly string[];
+    /** Hermes profile（`-p`） */
+    profile?: string;
+    /** toolsets（`-t`） */
+    toolsets?: string;
+    /** 模型（`-m`） */
+    model?: string;
+    /** 工作目录（`--in`） */
+    cwd?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    concurrency?: number;
+    /** `--usage-file` 临时目录 */
+    usageDir?: string;
+}
+/**
+ * Hermes 一次性非交互适配器：`hermes [-p P] [-t T] [-m M] [--in DIR] -z <prompt> --usage-file <tmp>`。
+ * 成功 → 结果 = stdout（截断）；超时/非零退出 → `failed` 带原因与 stderr 尾巴。
+ */
+export declare class HermesAgent implements TaskExecutor {
+    private readonly options;
+    private readonly sem;
+    constructor(options?: HermesAgentOptions);
+    private argv;
+    execute(task: TaskState): Promise<ExecutionOutcome>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/runtime/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/runtime/agent.ts"],"names":[],"mappings":"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"}

package/dist/runtime/agent.js

@@ -0,0 +1,260 @@
+// Fleet Agent 适配器（M4）：按 `to.agent` 名字路由到可插拔执行器。
+//
+// 安全与工程约束：
+// - **参数数组传参**（绝不 shell 拼接，防注入）；
+// - 超时 / 非零退出 / 输出超限 各自语义明确（超时与非零 → 任务 `failed` 带原因）；
+// - **不继承 daemon 的全量 env**：只透传 `ENV_ALLOWLIST`（PATH/HOME/… 运行所需）+ 调用方显式
+//   给出的 `options.env`；凭据/令牌不外流。同时不打印/不落盘任何 env 值；
+// - 工作目录与并发上限可配。
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** 按 agent 名字选择执行器；**未知 agent 返回 null**（调用方须显式失败，不得静默回退）。 */
+export class ExecutorRegistry {
+    exact = new Map();
+    wildcard = null;
+    /** 注册某 agent 名；`'*'` 为通配（仅匹配 `to.agent === '*'`）。 */
+    register(agent, executor) {
+        if (agent === '*')
+            this.wildcard = executor;
+        else
+            this.exact.set(agent, executor);
+        return this;
+    }
+    resolve(agent) {
+        if (agent === '*')
+            return this.wildcard;
+        return this.exact.get(agent) ?? null; // 显式：不 fallback 到通配
+    }
+    has(agent) {
+        return agent === '*' ? this.wildcard !== null : this.exact.has(agent);
+    }
+    names() {
+        return [...this.exact.keys()].sort();
+    }
+}
+/** UTF-8 安全截断（按字节），附截断标记。 */
+export function truncateOutput(text, maxBytes) {
+    const buf = Buffer.from(text, 'utf-8');
+    if (buf.byteLength <= maxBytes)
+        return { text, truncated: false, totalBytes: buf.byteLength };
+    const head = buf.subarray(0, maxBytes).toString('utf-8');
+    return { text: `${head}\n…[truncated ${buf.byteLength - maxBytes} bytes]`, truncated: true, totalBytes: buf.byteLength };
+}
+/** 简单并发闸（确定性：FIFO）。 */
+class Semaphore {
+    limit;
+    active = 0;
+    waiters = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async acquire() {
+        if (this.active < this.limit) {
+            this.active += 1;
+            return;
+        }
+        await new Promise((resolve) => this.waiters.push(resolve));
+        this.active += 1;
+    }
+    release() {
+        this.active -= 1;
+        const next = this.waiters.shift();
+        if (next)
+            next();
+    }
+}
+/**
+ * 允许透传给被派发 Agent 的环境变量**白名单**（非私密运行所需）。
+ * 其余（尤其凭据/令牌）**一律不继承**——daemon 的 env 不外流。
+ */
+export const ENV_ALLOWLIST = [
+    'PATH',
+    'HOME',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'SHELL',
+    'USER',
+    'LOGNAME',
+    'TMPDIR',
+    'TEMP',
+    'TMP',
+    'HERMES_HOME', // Hermes profile 解析（非密）
+    // Windows 运行所需（存在才带）
+    'SystemRoot',
+    'PATHEXT',
+    'COMSPEC',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'ProgramData',
+];
+/** 按白名单构建子进程 env；`extra`（调用方显式给出）覆盖白名单同名项。 */
+export function buildChildEnv(extra, source = process.env) {
+    const env = {};
+    for (const key of ENV_ALLOWLIST) {
+        const value = source[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(extra ?? {}))
+        env[key] = value;
+    return env;
+}
+/** 以参数数组执行命令；捕获 stdout/stderr（stderr 保留尾部）；超时 kill。 */
+export async function runOnce(options) {
+    const limit = options.maxOutputBytes;
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(options.command, [...options.args], {
+                ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+                // 只继承白名单 + 显式 env；不把 daemon 的全量环境（含凭据）传给被派发 Agent。
+                env: buildChildEnv(options.env),
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            resolve({ code: null, stdout: '', stdoutBytes: 0, stderrTail: error.message, timedOut: false });
+            return;
+        }
+        const outChunks = [];
+        const errChunks = [];
+        let outBytes = 0;
+        let totalOutBytes = 0;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, Math.max(1, options.timeoutMs));
+        child.stdout?.on('data', (chunk) => {
+            totalOutBytes += chunk.length;
+            if (outBytes < limit) {
+                // 按**字节**精确封顶：大 chunk 只取剩余额度，避免截断结果超过 maxOutputBytes。
+                const remaining = limit - outBytes;
+                const piece = chunk.length <= remaining ? chunk : chunk.subarray(0, remaining);
+                outChunks.push(piece);
+                outBytes += piece.length;
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            errChunks.push(chunk);
+            while (errChunks.length > 0 && Buffer.concat(errChunks).length > 8192)
+                errChunks.shift();
+        });
+        const finish = (code) => {
+            clearTimeout(timer);
+            const stdout = Buffer.concat(outChunks).toString('utf-8');
+            const stderrTail = Buffer.concat(errChunks).toString('utf-8').trim().slice(-800);
+            resolve({ code, stdout, stdoutBytes: totalOutBytes, stderrTail, timedOut });
+        };
+        child.on('error', () => finish(null));
+        child.on('close', (code) => finish(code));
+    });
+}
+/** 通用「命令行 Agent」执行器。 */
+export class CommandAgent {
+    options;
+    sem;
+    constructor(options) {
+        this.options = options;
+        this.sem = new Semaphore(Math.max(1, options.concurrency ?? 1));
+    }
+    async execute(task) {
+        await this.sem.acquire();
+        try {
+            const args = [
+                ...(this.options.baseArgs ?? []),
+                ...(this.options.promptArgs ? this.options.promptArgs(task) : ['-z', task.intent]),
+            ];
+            const timeoutMs = this.options.timeoutMs ?? 60_000;
+            const maxOutputBytes = this.options.maxOutputBytes ?? 65_536;
+            const result = await runOnce({
+                command: this.options.command,
+                args,
+                ...(this.options.cwd !== undefined ? { cwd: this.options.cwd } : {}),
+                ...(this.options.env !== undefined ? { env: this.options.env } : {}),
+                timeoutMs,
+                maxOutputBytes,
+            });
+            if (result.timedOut)
+                return { ok: false, reason: `TIMEOUT after ${timeoutMs}ms` };
+            if (result.code !== 0) {
+                return { ok: false, reason: `EXIT_${result.code}${result.stderrTail ? `: ${result.stderrTail}` : ''}` };
+            }
+            const stored = result.stdout.trim();
+            const text = result.stdoutBytes > maxOutputBytes ? `${stored}\n…[truncated ${result.stdoutBytes - maxOutputBytes} bytes]` : stored;
+            const resultRef = this.options.resultRef ? this.options.resultRef(text, task) : text;
+            return { ok: true, resultRef };
+        }
+        finally {
+            this.sem.release();
+        }
+    }
+}
+/**
+ * Hermes 一次性非交互适配器：`hermes [-p P] [-t T] [-m M] [--in DIR] -z <prompt> --usage-file <tmp>`。
+ * 成功 → 结果 = stdout（截断）；超时/非零退出 → `failed` 带原因与 stderr 尾巴。
+ */
+export class HermesAgent {
+    options;
+    sem;
+    constructor(options = {}) {
+        this.options = options;
+        this.sem = new Semaphore(Math.max(1, options.concurrency ?? 2));
+    }
+    argv(prompt, usagePath) {
+        const args = [...(this.options.commandArgs ?? [])];
+        if (this.options.profile)
+            args.push('-p', this.options.profile);
+        if (this.options.toolsets)
+            args.push('-t', this.options.toolsets);
+        if (this.options.model)
+            args.push('-m', this.options.model);
+        if (this.options.cwd)
+            args.push('--in', this.options.cwd);
+        args.push('-z', prompt, '--usage-file', usagePath);
+        return args;
+    }
+    async execute(task) {
+        await this.sem.acquire();
+        const dir = await mkdtemp(join(this.options.usageDir ?? tmpdir(), 'fleet-hermes-'));
+        const usagePath = join(dir, 'usage.json');
+        try {
+            const timeoutMs = this.options.timeoutMs ?? 600_000;
+            const maxOutputBytes = this.options.maxOutputBytes ?? 65_536;
+            const result = await runOnce({
+                command: this.options.hermesPath ?? 'hermes',
+                args: this.argv(task.intent, usagePath),
+                ...(this.options.cwd !== undefined ? { cwd: this.options.cwd } : {}),
+                timeoutMs,
+                maxOutputBytes,
+            });
+            if (result.timedOut)
+                return { ok: false, reason: `TIMEOUT after ${timeoutMs}ms` };
+            if (result.code !== 0) {
+                return { ok: false, reason: `EXIT_${result.code}${result.stderrTail ? `: ${result.stderrTail}` : ''}` };
+            }
+            const stored = result.stdout.trim();
+            const text = result.stdoutBytes > maxOutputBytes ? `${stored}\n…[truncated ${result.stdoutBytes - maxOutputBytes} bytes]` : stored;
+            // usage 仅用于观测 sessionId；解析失败不影响结果。
+            let sessionId;
+            try {
+                const usage = JSON.parse(await readFile(usagePath, 'utf-8'));
+                sessionId = usage.session_id;
+            }
+            catch {
+                sessionId = undefined;
+            }
+            return { ok: true, ...(sessionId !== undefined ? { reason: `session:${sessionId}` } : {}), resultRef: text };
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 20 });
+            this.sem.release();
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/runtime/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/runtime/agent.ts"],"names":[],"mappings":"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"}

package/dist/runtime/executor.d.ts

@@ -0,0 +1,42 @@
+import type { TaskState } from '../model.js';
+export interface ExecutionOutcome {
+    ok: boolean;
+    resultRef?: string;
+    reason?: string;
+}
+/** 执行器契约：**按 taskId 幂等**（同一任务重复执行必须得到同一结果且无副作用）。 */
+export interface TaskExecutor {
+    execute(task: TaskState): Promise<ExecutionOutcome>;
+}
+/** 内置 echo 执行器：结果与意图确定性绑定（幂等、无副作用）。 */
+export declare class EchoExecutor implements TaskExecutor {
+    execute(task: TaskState): Promise<ExecutionOutcome>;
+}
+/** 期望结果（供校验）：与 `EchoExecutor` 对齐。 */
+export declare function echoResultFor(intent: string): string;
+interface LogEntry {
+    taskId: string;
+    resultRef: string;
+}
+/** 执行记录：持久化「已执行的 taskId → 结果」，跨重启/重复投递去重执行。 */
+export declare class ExecutionLog {
+    private readonly path;
+    private readonly entries;
+    private readonly index;
+    private constructor();
+    static open(path: string): Promise<ExecutionLog>;
+    has(taskId: string): boolean;
+    resultOf(taskId: string): string | undefined;
+    /** 记录一次真实执行（若已存在则不重复追加）。 */
+    record(taskId: string, resultRef: string): Promise<void>;
+    all(): LogEntry[];
+    size(): number;
+    close(): Promise<void>;
+}
+/**
+ * 按 taskId 至多执行一次：已记录则直接返回记录结果（不再次调用执行器）。
+ * 这保证「重复投递不重复执行」与「重启不重复执行」。
+ */
+export declare function executeOnce(task: TaskState, executor: TaskExecutor, log: ExecutionLog): Promise<ExecutionOutcome>;
+export {};
+//# sourceMappingURL=executor.d.ts.map

package/dist/runtime/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/runtime/executor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACrD;AAED,uCAAuC;AACvC,qBAAa,YAAa,YAAW,YAAY;IACzC,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG1D;AAED,qCAAqC;AACrC,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,UAAU,QAAQ;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IAEnD,OAAO;WAIM,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAyBtD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5C,4BAA4B;IACtB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,GAAG,IAAI,QAAQ,EAAE;IAIjB,IAAI,IAAI,MAAM;IAIR,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,YAAY,EACtB,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAM3B"}

package/dist/runtime/executor.js

@@ -0,0 +1,87 @@
+// 可插拔执行器（M2）：内置 `echo`；执行记录（ExecutionLog）保证**按 taskId 至多执行一次**。
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** 内置 echo 执行器：结果与意图确定性绑定（幂等、无副作用）。 */
+export class EchoExecutor {
+    async execute(task) {
+        return { ok: true, resultRef: `echo:${task.intent}` };
+    }
+}
+/** 期望结果（供校验）：与 `EchoExecutor` 对齐。 */
+export function echoResultFor(intent) {
+    return `echo:${intent}`;
+}
+/** 执行记录：持久化「已执行的 taskId → 结果」，跨重启/重复投递去重执行。 */
+export class ExecutionLog {
+    path;
+    entries = [];
+    index = new Map();
+    constructor(path) {
+        this.path = path;
+    }
+    static async open(path) {
+        const log = new ExecutionLog(path);
+        await mkdir(dirname(path), { recursive: true });
+        let raw = '';
+        try {
+            raw = await readFile(path, 'utf-8');
+        }
+        catch {
+            raw = '';
+        }
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            try {
+                const entry = JSON.parse(trimmed);
+                if (!log.index.has(entry.taskId)) {
+                    log.index.set(entry.taskId, entry.resultRef);
+                    log.entries.push(entry);
+                }
+            }
+            catch {
+                continue; // 半行/损坏行跳过
+            }
+        }
+        return log;
+    }
+    has(taskId) {
+        return this.index.has(taskId);
+    }
+    resultOf(taskId) {
+        return this.index.get(taskId);
+    }
+    /** 记录一次真实执行（若已存在则不重复追加）。 */
+    async record(taskId, resultRef) {
+        if (this.index.has(taskId))
+            return;
+        const entry = { taskId, resultRef };
+        await appendFile(this.path, `${JSON.stringify(entry)}\n`, 'utf-8');
+        this.index.set(taskId, resultRef);
+        this.entries.push(entry);
+    }
+    all() {
+        return [...this.entries];
+    }
+    size() {
+        return this.entries.length;
+    }
+    async close() {
+        // 追加即时落盘；无长连接。
+    }
+}
+/**
+ * 按 taskId 至多执行一次：已记录则直接返回记录结果（不再次调用执行器）。
+ * 这保证「重复投递不重复执行」与「重启不重复执行」。
+ */
+export async function executeOnce(task, executor, log) {
+    const existing = log.resultOf(task.taskId);
+    if (existing !== undefined)
+        return { ok: true, resultRef: existing };
+    const outcome = await executor.execute(task);
+    if (outcome.ok)
+        await log.record(task.taskId, outcome.resultRef ?? '');
+    return outcome;
+}
+//# sourceMappingURL=executor.js.map

package/dist/runtime/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/runtime/executor.ts"],"names":[],"mappings":"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"}

package/dist/runtime/fairness.d.ts

@@ -0,0 +1,25 @@
+import type { TaskState } from '../model.js';
+export interface FairOrderOptions {
+    /** 单一发送方份额上限（有其它待处理发送方时）；默认 0.5 */
+    shareCap?: number;
+}
+/**
+ * 轮转序：每一步选「已服务次数最少」的发送方（tie：剩余最多 → device 字典序），
+ * 组内按 `taskId` 逻辑序。返回 taskId 的确定序。
+ */
+export declare function fairOrder(pending: readonly TaskState[], options?: FairOrderOptions): string[];
+export interface AgentConcurrencyOptions {
+    /** 每个目标 Agent 的并发上限（默认 2；仅本地调度门，无全局账本） */
+    perAgent?: number;
+    /** `(来源设备, 目标 Agent)` 准入配额（默认 Infinity = 不限） */
+    perPair?: number;
+}
+/**
+ * 在某轮内按「目标 Agent 并发 + (来源设备,目标 Agent) 配额」过滤可执行 taskId（保序）。
+ * `inFlight` 为已在途/已执行的计数（本地记账；调用方维护）。
+ */
+export declare function admitByConcurrency(ordered: readonly TaskState[], inFlight: {
+    agent: ReadonlyMap<string, number>;
+    pair: ReadonlyMap<string, number>;
+}, options?: AgentConcurrencyOptions): string[];
+//# sourceMappingURL=fairness.d.ts.map

package/dist/runtime/fairness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fairness.d.ts","sourceRoot":"","sources":["../../src/runtime/fairness.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,EAAE,CAyCjG;AAED,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,QAAQ,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EACnF,OAAO,GAAE,uBAA4B,GACpC,MAAM,EAAE,CAgBV"}

package/dist/runtime/fairness.js

@@ -0,0 +1,79 @@
+// W1 公平准入（本地、确定性、无墙钟）：收件按 `(from.device, 逻辑序)` 轮转；
+// 有其它待处理发送方时，单一发送方**份额 ≤ 50%**；`(来源设备, 目标 Agent)` 准入配额；
+// 每 Agent 并发默认 2。全部为纯函数，便于判别性测试与全端一致。
+/**
+ * 轮转序：每一步选「已服务次数最少」的发送方（tie：剩余最多 → device 字典序），
+ * 组内按 `taskId` 逻辑序。返回 taskId 的确定序。
+ */
+export function fairOrder(pending, options = {}) {
+    const shareCap = options.shareCap ?? 0.5;
+    const groups = new Map();
+    for (const state of pending) {
+        const list = groups.get(state.from.device);
+        if (list)
+            list.push(state);
+        else
+            groups.set(state.from.device, [state]);
+    }
+    for (const list of groups.values())
+        list.sort((a, b) => (a.taskId < b.taskId ? -1 : a.taskId > b.taskId ? 1 : 0));
+    const served = new Map();
+    for (const device of groups.keys())
+        served.set(device, 0);
+    const order = [];
+    const total = pending.length;
+    while (order.length < total) {
+        const active = [...groups.keys()]
+            .filter((d) => (groups.get(d)?.length ?? 0) > 0)
+            .sort((a, b) => {
+            const sa = served.get(a);
+            const sb = served.get(b);
+            if (sa !== sb)
+                return sa - sb;
+            const ra = groups.get(a).length;
+            const rb = groups.get(b).length;
+            if (ra !== rb)
+                return rb - ra;
+            return a < b ? -1 : a > b ? 1 : 0;
+        });
+        if (active.length === 0)
+            break;
+        let pick = active[0];
+        // 份额上限：若选它会让其份额 > cap 且还有尚未达到同等优先级的其它活跃发送方 → 换下一个
+        const cap = shareCap * (order.length + 1);
+        if (served.get(pick) + 1 > cap) {
+            const alternative = active.find((d) => served.get(d) + 1 <= cap);
+            if (alternative !== undefined)
+                pick = alternative;
+        }
+        const list = groups.get(pick);
+        const next = list.shift();
+        order.push(next.taskId);
+        served.set(pick, served.get(pick) + 1);
+    }
+    return order;
+}
+/**
+ * 在某轮内按「目标 Agent 并发 + (来源设备,目标 Agent) 配额」过滤可执行 taskId（保序）。
+ * `inFlight` 为已在途/已执行的计数（本地记账；调用方维护）。
+ */
+export function admitByConcurrency(ordered, inFlight, options = {}) {
+    const perAgent = options.perAgent ?? 2;
+    const perPair = options.perPair ?? Number.POSITIVE_INFINITY;
+    const agentCount = new Map(inFlight.agent);
+    const pairCount = new Map(inFlight.pair);
+    const admitted = [];
+    for (const state of ordered) {
+        const agent = state.to.agent;
+        const pair = `${state.from.device}->${agent}`;
+        if ((agentCount.get(agent) ?? 0) >= perAgent)
+            continue;
+        if ((pairCount.get(pair) ?? 0) >= perPair)
+            continue;
+        agentCount.set(agent, (agentCount.get(agent) ?? 0) + 1);
+        pairCount.set(pair, (pairCount.get(pair) ?? 0) + 1);
+        admitted.push(state.taskId);
+    }
+    return admitted;
+}
+//# sourceMappingURL=fairness.js.map

package/dist/runtime/fairness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fairness.js","sourceRoot":"","sources":["../../src/runtime/fairness.ts"],"names":[],"mappings":"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"}