@mebular/fleet 0.0.0-stage → 0.1.0

package/src/quota.ts

@@ -0,0 +1,112 @@
+// Fleet 本地配额（M1）：**每设备对自己发出的量本地记账**，超额本地拒绝或排队。
+//
+// 禁中心化：无注册服务、无全局账本、无跨端对账；不同设备的配额互不影响（见 DESIGN.md §4）。
+
+/** 准入判定。 */
+export type QuotaDecision = 'accepted' | 'queued' | 'rejected';
+
+/** 每设备快照。 */
+export interface QuotaSnapshot {
+  device: string;
+  used: number;
+  queued: number;
+  rejected: number;
+}
+
+/** 构造选项。 */
+export interface LocalQuotaOptions {
+  /** 每设备（对**自己发出**）的上限 */
+  limitPerDevice: number;
+  /** 超额策略：`queue` 进本地队列；`reject` 直接拒绝。默认 `queue`。 */
+  onOverflow?: 'queue' | 'reject';
+}
+
+function assertAmount(amount: number): void {
+  if (!Number.isInteger(amount) || amount <= 0) {
+    throw new Error(`quota amount 必须为正整数：${amount}`);
+  }
+}
+
+/** 每设备本地配额账本（确定性、纯本地）。 */
+export class LocalQuota {
+  private readonly limit: number;
+  private readonly overflow: 'queue' | 'reject';
+  private readonly usedMap = new Map<string, number>();
+  private readonly queuedMap = new Map<string, number>();
+  private readonly rejectedMap = new Map<string, number>();
+
+  constructor(options: LocalQuotaOptions) {
+    if (!Number.isInteger(options.limitPerDevice) || options.limitPerDevice <= 0) {
+      throw new Error(`limitPerDevice 必须为正整数：${options.limitPerDevice}`);
+    }
+    this.limit = options.limitPerDevice;
+    this.overflow = options.onOverflow ?? 'queue';
+  }
+
+  private static bump(map: Map<string, number>, key: string, amount: number): void {
+    map.set(key, (map.get(key) ?? 0) + amount);
+  }
+
+  /** 请求发出 `amount` 单位：返回本机判定（`accepted` / `queued` / `rejected`）。 */
+  decide(device: string, amount = 1): QuotaDecision {
+    assertAmount(amount);
+    const used = this.usedMap.get(device) ?? 0;
+    if (used + amount <= this.limit) {
+      LocalQuota.bump(this.usedMap, device, amount);
+      return 'accepted';
+    }
+    if (this.overflow === 'reject') {
+      LocalQuota.bump(this.rejectedMap, device, amount);
+      return 'rejected';
+    }
+    LocalQuota.bump(this.queuedMap, device, amount);
+    return 'queued';
+  }
+
+  /** 容量释放（如队列/在途被消费）：从 `used` 扣减（不为负）。 */
+  release(device: string, amount = 1): void {
+    assertAmount(amount);
+    const used = this.usedMap.get(device) ?? 0;
+    this.usedMap.set(device, Math.max(0, used - amount));
+  }
+
+  /**
+   * 把本地队列里的量搬迁到 `used`（容量允许时）；返回搬迁成功的量。
+   * 仅本地排队消化，无跨端协调。
+   */
+  drainQueue(device: string, capacity = this.limit): number {
+    if (!Number.isInteger(capacity) || capacity < 0) throw new Error(`capacity 非法：${capacity}`);
+    const queued = this.queuedMap.get(device) ?? 0;
+    const used = this.usedMap.get(device) ?? 0;
+    const room = Math.max(0, capacity - used);
+    const moved = Math.min(queued, room);
+    if (moved > 0) {
+      this.queuedMap.set(device, queued - moved);
+      this.usedMap.set(device, used + moved);
+    }
+    return moved;
+  }
+
+  used(device: string): number {
+    return this.usedMap.get(device) ?? 0;
+  }
+
+  queued(device: string): number {
+    return this.queuedMap.get(device) ?? 0;
+  }
+
+  rejected(device: string): number {
+    return this.rejectedMap.get(device) ?? 0;
+  }
+
+  /** 每设备快照（按 device 字典序，确定性）。 */
+  snapshot(): QuotaSnapshot[] {
+    const devices = new Set<string>([...this.usedMap.keys(), ...this.queuedMap.keys(), ...this.rejectedMap.keys()]);
+    return [...devices].sort().map((device) => ({
+      device,
+      used: this.usedMap.get(device) ?? 0,
+      queued: this.queuedMap.get(device) ?? 0,
+      rejected: this.rejectedMap.get(device) ?? 0,
+    }));
+  }
+}

package/src/runtime/agent.ts

@@ -0,0 +1,313 @@
+// Fleet Agent 适配器（M4）：按 `to.agent` 名字路由到可插拔执行器。
+//
+// 安全与工程约束：
+// - **参数数组传参**（绝不 shell 拼接，防注入）；
+// - 超时 / 非零退出 / 输出超限 各自语义明确（超时与非零 → 任务 `failed` 带原因）；
+// - **不继承 daemon 的全量 env**：只透传 `ENV_ALLOWLIST`（PATH/HOME/… 运行所需）+ 调用方显式
+//   给出的 `options.env`；凭据/令牌不外流。同时不打印/不落盘任何 env 值；
+// - 工作目录与并发上限可配。
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { TaskState } from '../model.js';
+import type { ExecutionOutcome, TaskExecutor } from './executor.js';
+
+/** 按 agent 名字选择执行器；**未知 agent 返回 null**（调用方须显式失败，不得静默回退）。 */
+export class ExecutorRegistry {
+  private readonly exact = new Map<string, TaskExecutor>();
+  private wildcard: TaskExecutor | null = null;
+
+  /** 注册某 agent 名；`'*'` 为通配（仅匹配 `to.agent === '*'`）。 */
+  register(agent: string, executor: TaskExecutor): this {
+    if (agent === '*') this.wildcard = executor;
+    else this.exact.set(agent, executor);
+    return this;
+  }
+
+  resolve(agent: string): TaskExecutor | null {
+    if (agent === '*') return this.wildcard;
+    return this.exact.get(agent) ?? null; // 显式：不 fallback 到通配
+  }
+
+  has(agent: string): boolean {
+    return agent === '*' ? this.wildcard !== null : this.exact.has(agent);
+  }
+
+  names(): string[] {
+    return [...this.exact.keys()].sort();
+  }
+}
+
+/** UTF-8 安全截断（按字节），附截断标记。 */
+export function truncateOutput(text: string, maxBytes: number): { text: string; truncated: boolean; totalBytes: number } {
+  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 {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+  constructor(private readonly limit: number) {}
+  async acquire(): Promise<void> {
+    if (this.active < this.limit) {
+      this.active += 1;
+      return;
+    }
+    await new Promise<void>((resolve) => this.waiters.push(resolve));
+    this.active += 1;
+  }
+  release(): void {
+    this.active -= 1;
+    const next = this.waiters.shift();
+    if (next) next();
+  }
+}
+
+export interface SpawnResult {
+  code: number | null;
+  /** 已捕获的 stdout（至多 `maxOutputBytes` 字节） */
+  stdout: string;
+  /** stdout 的**总字节数**（含未捕获部分） */
+  stdoutBytes: number;
+  stderrTail: string;
+  timedOut: boolean;
+}
+
+/**
+ * 允许透传给被派发 Agent 的环境变量**白名单**（非私密运行所需）。
+ * 其余（尤其凭据/令牌）**一律不继承**——daemon 的 env 不外流。
+ */
+export const ENV_ALLOWLIST: readonly string[] = [
+  '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?: Readonly<Record<string, string>>,
+  source: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  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: {
+  command: string;
+  args: readonly string[];
+  cwd?: string;
+  env?: Readonly<Record<string, string>>;
+  timeoutMs: number;
+  maxOutputBytes: number;
+}): Promise<SpawnResult> {
+  const limit = options.maxOutputBytes;
+  return new Promise<SpawnResult>((resolve) => {
+    let child: ChildProcess;
+    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 as Error).message, timedOut: false });
+      return;
+    }
+    const outChunks: Buffer[] = [];
+    const errChunks: Buffer[] = [];
+    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: Buffer) => {
+      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: Buffer) => {
+      errChunks.push(chunk);
+      while (errChunks.length > 0 && Buffer.concat(errChunks).length > 8192) errChunks.shift();
+    });
+    const finish = (code: number | null): void => {
+      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));
+  });
+}
+
+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 class CommandAgent implements TaskExecutor {
+  private readonly sem: Semaphore;
+  constructor(private readonly options: CommandAgentOptions) {
+    this.sem = new Semaphore(Math.max(1, options.concurrency ?? 1));
+  }
+
+  async execute(task: TaskState): Promise<ExecutionOutcome> {
+    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();
+    }
+  }
+}
+
+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 class HermesAgent implements TaskExecutor {
+  private readonly sem: Semaphore;
+  constructor(private readonly options: HermesAgentOptions = {}) {
+    this.sem = new Semaphore(Math.max(1, options.concurrency ?? 2));
+  }
+
+  private argv(prompt: string, usagePath: string): string[] {
+    const args: string[] = [...(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: TaskState): Promise<ExecutionOutcome> {
+    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: string | undefined;
+      try {
+        const usage = JSON.parse(await readFile(usagePath, 'utf-8')) as { session_id?: string };
+        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();
+    }
+  }
+}

package/src/runtime/executor.ts

@@ -0,0 +1,114 @@
+// 可插拔执行器（M2）：内置 `echo`；执行记录（ExecutionLog）保证**按 taskId 至多执行一次**。
+
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+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 class EchoExecutor implements TaskExecutor {
+  async execute(task: TaskState): Promise<ExecutionOutcome> {
+    return { ok: true, resultRef: `echo:${task.intent}` };
+  }
+}
+
+/** 期望结果（供校验）：与 `EchoExecutor` 对齐。 */
+export function echoResultFor(intent: string): string {
+  return `echo:${intent}`;
+}
+
+interface LogEntry {
+  taskId: string;
+  resultRef: string;
+}
+
+/** 执行记录：持久化「已执行的 taskId → 结果」，跨重启/重复投递去重执行。 */
+export class ExecutionLog {
+  private readonly path: string;
+  private readonly entries: LogEntry[] = [];
+  private readonly index = new Map<string, string>();
+
+  private constructor(path: string) {
+    this.path = path;
+  }
+
+  static async open(path: string): Promise<ExecutionLog> {
+    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) as LogEntry;
+        if (!log.index.has(entry.taskId)) {
+          log.index.set(entry.taskId, entry.resultRef);
+          log.entries.push(entry);
+        }
+      } catch {
+        continue; // 半行/损坏行跳过
+      }
+    }
+    return log;
+  }
+
+  has(taskId: string): boolean {
+    return this.index.has(taskId);
+  }
+
+  resultOf(taskId: string): string | undefined {
+    return this.index.get(taskId);
+  }
+
+  /** 记录一次真实执行（若已存在则不重复追加）。 */
+  async record(taskId: string, resultRef: string): Promise<void> {
+    if (this.index.has(taskId)) return;
+    const entry: LogEntry = { taskId, resultRef };
+    await appendFile(this.path, `${JSON.stringify(entry)}\n`, 'utf-8');
+    this.index.set(taskId, resultRef);
+    this.entries.push(entry);
+  }
+
+  all(): LogEntry[] {
+    return [...this.entries];
+  }
+
+  size(): number {
+    return this.entries.length;
+  }
+
+  async close(): Promise<void> {
+    // 追加即时落盘；无长连接。
+  }
+}
+
+/**
+ * 按 taskId 至多执行一次：已记录则直接返回记录结果（不再次调用执行器）。
+ * 这保证「重复投递不重复执行」与「重启不重复执行」。
+ */
+export async function executeOnce(
+  task: TaskState,
+  executor: TaskExecutor,
+  log: ExecutionLog,
+): Promise<ExecutionOutcome> {
+  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;
+}

package/src/runtime/fairness.ts

@@ -0,0 +1,90 @@
+// W1 公平准入（本地、确定性、无墙钟）：收件按 `(from.device, 逻辑序)` 轮转；
+// 有其它待处理发送方时，单一发送方**份额 ≤ 50%**；`(来源设备, 目标 Agent)` 准入配额；
+// 每 Agent 并发默认 2。全部为纯函数，便于判别性测试与全端一致。
+
+import type { TaskState } from '../model.js';
+
+export interface FairOrderOptions {
+  /** 单一发送方份额上限（有其它待处理发送方时）；默认 0.5 */
+  shareCap?: number;
+}
+
+/**
+ * 轮转序：每一步选「已服务次数最少」的发送方（tie：剩余最多 → device 字典序），
+ * 组内按 `taskId` 逻辑序。返回 taskId 的确定序。
+ */
+export function fairOrder(pending: readonly TaskState[], options: FairOrderOptions = {}): string[] {
+  const shareCap = options.shareCap ?? 0.5;
+  const groups = new Map<string, TaskState[]>();
+  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<string, number>();
+  for (const device of groups.keys()) served.set(device, 0);
+  const order: string[] = [];
+  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;
+}
+
+export interface AgentConcurrencyOptions {
+  /** 每个目标 Agent 的并发上限（默认 2；仅本地调度门，无全局账本） */
+  perAgent?: number;
+  /** `(来源设备, 目标 Agent)` 准入配额（默认 Infinity = 不限） */
+  perPair?: number;
+}
+
+/**
+ * 在某轮内按「目标 Agent 并发 + (来源设备,目标 Agent) 配额」过滤可执行 taskId（保序）。
+ * `inFlight` 为已在途/已执行的计数（本地记账；调用方维护）。
+ */
+export function admitByConcurrency(
+  ordered: readonly TaskState[],
+  inFlight: { agent: ReadonlyMap<string, number>; pair: ReadonlyMap<string, number> },
+  options: AgentConcurrencyOptions = {},
+): string[] {
+  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: string[] = [];
+  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;
+}