@undefineds.co/xpod 0.3.46 → 0.3.49

package/dist/api/reconciler/ClientReconcilerCoordinator.js

@@ -0,0 +1,250 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientReconcilerCoordinator = exports.DEFAULT_CLIENT_RECONCILER_LEASE_TTL_MS = exports.DEFAULT_CLIENT_RECONCILER_HEARTBEAT_TTL_MS = void 0;
+const node_crypto_1 = require("node:crypto");
+const ioredis_1 = __importDefault(require("ioredis"));
+const global_logger_factory_1 = require("global-logger-factory");
+const coordination_1 = require("./coordination");
+const RedisClientLifecycle_1 = require("../../storage/redis/RedisClientLifecycle");
+exports.DEFAULT_CLIENT_RECONCILER_HEARTBEAT_TTL_MS = 45_000;
+exports.DEFAULT_CLIENT_RECONCILER_LEASE_TTL_MS = 30_000;
+class ClientReconcilerCoordinator {
+    constructor(options = {}) {
+        this.now = options.now ?? (() => new Date());
+        this.heartbeatTtlMs = options.heartbeatTtlMs ?? exports.DEFAULT_CLIENT_RECONCILER_HEARTBEAT_TTL_MS;
+        this.leaseTtlMs = options.leaseTtlMs ?? exports.DEFAULT_CLIENT_RECONCILER_LEASE_TTL_MS;
+        this.backend = options.redisUrl
+            ? new RedisClientReconcilerCoordinatorBackend({
+                redisUrl: options.redisUrl,
+                namespace: options.namespace,
+                heartbeatTtlMs: this.heartbeatTtlMs,
+            })
+            : new InMemoryClientReconcilerCoordinatorBackend({
+                heartbeatTtlMs: this.heartbeatTtlMs,
+            });
+    }
+    async upsertClientCapability(input) {
+        const now = this.now();
+        const capability = {
+            clientId: requireNonEmptyString(input.clientId, 'clientId'),
+            kind: normalizeClientKind(input.kind),
+            user: requireNonEmptyString(input.user, 'user'),
+            canCoordinateClientOwnedThread: input.canCoordinateClientOwnedThread ?? false,
+            canRunAgent: input.canRunAgent ?? false,
+            workspaces: sanitizeWorkspaces(input.workspaces),
+            heartbeatAt: parseDateOrNow(input.heartbeatAt, now).toISOString(),
+        };
+        await this.backend.sweepExpired(now);
+        return this.backend.upsertClientCapability(capability);
+    }
+    async listClientCapabilities(user) {
+        const now = this.now();
+        await this.backend.sweepExpired(now);
+        return this.backend.listClientCapabilities(requireNonEmptyString(user, 'user'));
+    }
+    async activate(input) {
+        const now = this.now();
+        const thread = requireNonEmptyString(input.thread, 'thread');
+        const ownerUser = requireNonEmptyString(input.ownerUser, 'ownerUser');
+        await this.backend.sweepExpired(now);
+        const currentLease = await this.backend.getLease(thread);
+        const clients = await this.backend.listClientCapabilities(ownerUser);
+        const lease = (0, coordination_1.activateClientReconciler)({
+            thread,
+            ownerUser,
+            clients,
+            currentLease,
+            now,
+            heartbeatTtlMs: this.heartbeatTtlMs,
+            leaseTtlMs: this.leaseTtlMs,
+            fencingToken: (0, node_crypto_1.randomUUID)(),
+        });
+        if (!lease) {
+            return undefined;
+        }
+        return this.backend.saveLease(lease, this.leaseTtlMs);
+    }
+    async getLease(thread) {
+        const now = this.now();
+        await this.backend.sweepExpired(now);
+        const lease = await this.backend.getLease(requireNonEmptyString(thread, 'thread'));
+        return (0, coordination_1.isClientReconcilerLeaseActive)(lease, now) ? lease : undefined;
+    }
+    async releaseLease(input) {
+        await this.backend.sweepExpired(this.now());
+        return this.backend.releaseLease({
+            thread: requireNonEmptyString(input.thread, 'thread'),
+            ownerUser: requireNonEmptyString(input.ownerUser, 'ownerUser'),
+            clientId: requireNonEmptyString(input.clientId, 'clientId'),
+        });
+    }
+    async close() {
+        await this.backend.close?.();
+    }
+}
+exports.ClientReconcilerCoordinator = ClientReconcilerCoordinator;
+class InMemoryClientReconcilerCoordinatorBackend {
+    constructor(options) {
+        this.clients = new Map();
+        this.leases = new Map();
+        this.heartbeatTtlMs = options.heartbeatTtlMs;
+    }
+    async upsertClientCapability(capability) {
+        this.clients.set(clientKey(capability.user, capability.clientId), { ...capability, workspaces: [...capability.workspaces] });
+        return { ...capability, workspaces: [...capability.workspaces] };
+    }
+    async listClientCapabilities(user) {
+        return Array.from(this.clients.values())
+            .filter((client) => client.user === user)
+            .map((client) => ({ ...client, workspaces: [...client.workspaces] }));
+    }
+    async getLease(thread) {
+        const lease = this.leases.get(thread);
+        return lease ? { ...lease } : undefined;
+    }
+    async saveLease(lease) {
+        this.leases.set(lease.thread, { ...lease });
+        return { ...lease };
+    }
+    async releaseLease(input) {
+        const lease = this.leases.get(input.thread);
+        if (!lease || lease.ownerUser !== input.ownerUser || lease.ownerClientId !== input.clientId) {
+            return false;
+        }
+        return this.leases.delete(input.thread);
+    }
+    async sweepExpired(now) {
+        for (const [key, client] of this.clients) {
+            const heartbeatAt = Date.parse(client.heartbeatAt);
+            if (!Number.isFinite(heartbeatAt) || now.getTime() - heartbeatAt > this.heartbeatTtlMs) {
+                this.clients.delete(key);
+            }
+        }
+        for (const [thread, lease] of this.leases) {
+            if (!(0, coordination_1.isClientReconcilerLeaseActive)(lease, now)) {
+                this.leases.delete(thread);
+            }
+        }
+    }
+}
+class RedisClientReconcilerCoordinatorBackend {
+    constructor(options) {
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.shuttingDown = false;
+        this.namespace = options.namespace ?? 'xpod:coordination:';
+        this.heartbeatTtlMs = options.heartbeatTtlMs;
+        this.redis = new ioredis_1.default(options.redisUrl, { lazyConnect: false });
+        (0, RedisClientLifecycle_1.attachRedisClientErrorHandler)(this.redis, {
+            logger: this.logger,
+            label: 'ClientReconcilerCoordinator',
+            isShuttingDown: () => this.shuttingDown,
+        });
+    }
+    async upsertClientCapability(capability) {
+        await this.redis.set(this.clientStorageKey(capability.user, capability.clientId), JSON.stringify(capability), 'PX', this.heartbeatTtlMs);
+        return { ...capability, workspaces: [...capability.workspaces] };
+    }
+    async listClientCapabilities(user) {
+        const keys = await this.scanKeys(`${this.clientStoragePrefix(user)}*`);
+        if (keys.length === 0) {
+            return [];
+        }
+        const raws = await this.redis.mget(keys);
+        return raws
+            .map((raw) => parseJson(raw))
+            .filter((client) => Boolean(client && client.user === user));
+    }
+    async getLease(thread) {
+        return parseJson(await this.redis.get(this.leaseStorageKey(thread)));
+    }
+    async saveLease(lease, ttlMs) {
+        await this.redis.set(this.leaseStorageKey(lease.thread), JSON.stringify(lease), 'PX', ttlMs);
+        return { ...lease };
+    }
+    async releaseLease(input) {
+        const key = this.leaseStorageKey(input.thread);
+        const released = await this.redis.eval(`local raw = redis.call('GET', KEYS[1])
+       if not raw then return 0 end
+       local value = cjson.decode(raw)
+       if value['ownerUser'] == ARGV[1] and value['ownerClientId'] == ARGV[2] then
+         return redis.call('DEL', KEYS[1])
+       end
+       return 0`, 1, key, input.ownerUser, input.clientId);
+        return released === 1;
+    }
+    async sweepExpired(_now) {
+        // Redis key TTL owns expiry. No active sweep is required.
+    }
+    async close() {
+        this.shuttingDown = true;
+        await (0, RedisClientLifecycle_1.closeRedisClient)(this.redis, {
+            logger: this.logger,
+            label: 'ClientReconcilerCoordinator',
+        });
+    }
+    clientStoragePrefix(user) {
+        return `${this.namespace}client:${hash(user)}:`;
+    }
+    clientStorageKey(user, clientId) {
+        return `${this.clientStoragePrefix(user)}${encodeURIComponent(clientId)}`;
+    }
+    leaseStorageKey(thread) {
+        return `${this.namespace}lease:${hash(thread)}`;
+    }
+    async scanKeys(match) {
+        const keys = [];
+        let cursor = '0';
+        do {
+            const [nextCursor, batch] = await this.redis.scan(cursor, 'MATCH', match, 'COUNT', 100);
+            cursor = nextCursor;
+            keys.push(...batch);
+        } while (cursor !== '0');
+        return keys;
+    }
+}
+function normalizeClientKind(kind) {
+    if (kind === 'cli' || kind === 'desktop' || kind === 'mobile' || kind === 'web') {
+        return kind;
+    }
+    throw new Error('kind must be one of cli, desktop, mobile, web');
+}
+function sanitizeWorkspaces(workspaces) {
+    if (!Array.isArray(workspaces)) {
+        return [];
+    }
+    return Array.from(new Set(workspaces.filter((ref) => typeof ref === 'string' && ref.length > 0)));
+}
+function parseDateOrNow(value, now) {
+    if (typeof value !== 'string') {
+        return now;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed) : now;
+}
+function requireNonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${field} is required`);
+    }
+    return value.trim();
+}
+function clientKey(user, clientId) {
+    return `${user}\u0000${clientId}`;
+}
+function hash(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, 32);
+}
+function parseJson(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=ClientReconcilerCoordinator.js.map

package/dist/api/reconciler/ClientReconcilerCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientReconcilerCoordinator.js","sourceRoot":"","sources":["../../../src/api/reconciler/ClientReconcilerCoordinator.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport Redis from 'ioredis';\nimport { getLoggerFor } from 'global-logger-factory';\nimport {\n  activateClientReconciler,\n  isClientReconcilerLeaseActive,\n  type ClientCapability,\n  type ClientKind,\n  type ClientReconcilerLease,\n} from './coordination';\nimport {\n  attachRedisClientErrorHandler,\n  closeRedisClient,\n} from '../../storage/redis/RedisClientLifecycle';\n\nexport const DEFAULT_CLIENT_RECONCILER_HEARTBEAT_TTL_MS = 45_000;\nexport const DEFAULT_CLIENT_RECONCILER_LEASE_TTL_MS = 30_000;\n\nexport interface ClientReconcilerCoordinatorOptions {\n  redisUrl?: string;\n  now?: () => Date;\n  heartbeatTtlMs?: number;\n  leaseTtlMs?: number;\n  namespace?: string;\n}\n\nexport interface UpsertClientCapabilityInput {\n  clientId: string;\n  kind: ClientKind;\n  user: string;\n  canCoordinateClientOwnedThread?: boolean;\n  canRunAgent?: boolean;\n  workspaces?: string[];\n  heartbeatAt?: string;\n}\n\nexport interface ActivateClientReconcilerLeaseInput {\n  thread: string;\n  ownerUser: string;\n  requesterClientId?: string;\n}\n\nexport interface ReleaseClientReconcilerLeaseInput {\n  thread: string;\n  ownerUser: string;\n  clientId: string;\n}\n\ninterface ClientReconcilerCoordinatorBackend {\n  upsertClientCapability(capability: ClientCapability): Promise<ClientCapability>;\n  listClientCapabilities(user: string): Promise<ClientCapability[]>;\n  getLease(thread: string): Promise<ClientReconcilerLease | undefined>;\n  saveLease(lease: ClientReconcilerLease, ttlMs: number): Promise<ClientReconcilerLease>;\n  releaseLease(input: ReleaseClientReconcilerLeaseInput): Promise<boolean>;\n  sweepExpired(now: Date): Promise<void>;\n  close?(): Promise<void>;\n}\n\nexport class ClientReconcilerCoordinator {\n  private readonly now: () => Date;\n  private readonly heartbeatTtlMs: number;\n  private readonly leaseTtlMs: number;\n  private readonly backend: ClientReconcilerCoordinatorBackend;\n\n  public constructor(options: ClientReconcilerCoordinatorOptions = {}) {\n    this.now = options.now ?? (() => new Date());\n    this.heartbeatTtlMs = options.heartbeatTtlMs ?? DEFAULT_CLIENT_RECONCILER_HEARTBEAT_TTL_MS;\n    this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_CLIENT_RECONCILER_LEASE_TTL_MS;\n    this.backend = options.redisUrl\n      ? new RedisClientReconcilerCoordinatorBackend({\n        redisUrl: options.redisUrl,\n        namespace: options.namespace,\n        heartbeatTtlMs: this.heartbeatTtlMs,\n      })\n      : new InMemoryClientReconcilerCoordinatorBackend({\n        heartbeatTtlMs: this.heartbeatTtlMs,\n      });\n  }\n\n  public async upsertClientCapability(input: UpsertClientCapabilityInput): Promise<ClientCapability> {\n    const now = this.now();\n    const capability: ClientCapability = {\n      clientId: requireNonEmptyString(input.clientId, 'clientId'),\n      kind: normalizeClientKind(input.kind),\n      user: requireNonEmptyString(input.user, 'user'),\n      canCoordinateClientOwnedThread: input.canCoordinateClientOwnedThread ?? false,\n      canRunAgent: input.canRunAgent ?? false,\n      workspaces: sanitizeWorkspaces(input.workspaces),\n      heartbeatAt: parseDateOrNow(input.heartbeatAt, now).toISOString(),\n    };\n    await this.backend.sweepExpired(now);\n    return this.backend.upsertClientCapability(capability);\n  }\n\n  public async listClientCapabilities(user: string): Promise<ClientCapability[]> {\n    const now = this.now();\n    await this.backend.sweepExpired(now);\n    return this.backend.listClientCapabilities(requireNonEmptyString(user, 'user'));\n  }\n\n  public async activate(input: ActivateClientReconcilerLeaseInput): Promise<ClientReconcilerLease | undefined> {\n    const now = this.now();\n    const thread = requireNonEmptyString(input.thread, 'thread');\n    const ownerUser = requireNonEmptyString(input.ownerUser, 'ownerUser');\n    await this.backend.sweepExpired(now);\n\n    const currentLease = await this.backend.getLease(thread);\n    const clients = await this.backend.listClientCapabilities(ownerUser);\n    const lease = activateClientReconciler({\n      thread,\n      ownerUser,\n      clients,\n      currentLease,\n      now,\n      heartbeatTtlMs: this.heartbeatTtlMs,\n      leaseTtlMs: this.leaseTtlMs,\n      fencingToken: randomUUID(),\n    });\n\n    if (!lease) {\n      return undefined;\n    }\n    return this.backend.saveLease(lease, this.leaseTtlMs);\n  }\n\n  public async getLease(thread: string): Promise<ClientReconcilerLease | undefined> {\n    const now = this.now();\n    await this.backend.sweepExpired(now);\n    const lease = await this.backend.getLease(requireNonEmptyString(thread, 'thread'));\n    return isClientReconcilerLeaseActive(lease, now) ? lease : undefined;\n  }\n\n  public async releaseLease(input: ReleaseClientReconcilerLeaseInput): Promise<boolean> {\n    await this.backend.sweepExpired(this.now());\n    return this.backend.releaseLease({\n      thread: requireNonEmptyString(input.thread, 'thread'),\n      ownerUser: requireNonEmptyString(input.ownerUser, 'ownerUser'),\n      clientId: requireNonEmptyString(input.clientId, 'clientId'),\n    });\n  }\n\n  public async close(): Promise<void> {\n    await this.backend.close?.();\n  }\n}\n\nclass InMemoryClientReconcilerCoordinatorBackend implements ClientReconcilerCoordinatorBackend {\n  private readonly heartbeatTtlMs: number;\n  private readonly clients = new Map<string, ClientCapability>();\n  private readonly leases = new Map<string, ClientReconcilerLease>();\n\n  public constructor(options: { heartbeatTtlMs: number }) {\n    this.heartbeatTtlMs = options.heartbeatTtlMs;\n  }\n\n  public async upsertClientCapability(capability: ClientCapability): Promise<ClientCapability> {\n    this.clients.set(clientKey(capability.user, capability.clientId), { ...capability, workspaces: [ ...capability.workspaces ] });\n    return { ...capability, workspaces: [ ...capability.workspaces ] };\n  }\n\n  public async listClientCapabilities(user: string): Promise<ClientCapability[]> {\n    return Array.from(this.clients.values())\n      .filter((client) => client.user === user)\n      .map((client) => ({ ...client, workspaces: [ ...client.workspaces ] }));\n  }\n\n  public async getLease(thread: string): Promise<ClientReconcilerLease | undefined> {\n    const lease = this.leases.get(thread);\n    return lease ? { ...lease } : undefined;\n  }\n\n  public async saveLease(lease: ClientReconcilerLease): Promise<ClientReconcilerLease> {\n    this.leases.set(lease.thread, { ...lease });\n    return { ...lease };\n  }\n\n  public async releaseLease(input: ReleaseClientReconcilerLeaseInput): Promise<boolean> {\n    const lease = this.leases.get(input.thread);\n    if (!lease || lease.ownerUser !== input.ownerUser || lease.ownerClientId !== input.clientId) {\n      return false;\n    }\n    return this.leases.delete(input.thread);\n  }\n\n  public async sweepExpired(now: Date): Promise<void> {\n    for (const [ key, client ] of this.clients) {\n      const heartbeatAt = Date.parse(client.heartbeatAt);\n      if (!Number.isFinite(heartbeatAt) || now.getTime() - heartbeatAt > this.heartbeatTtlMs) {\n        this.clients.delete(key);\n      }\n    }\n    for (const [ thread, lease ] of this.leases) {\n      if (!isClientReconcilerLeaseActive(lease, now)) {\n        this.leases.delete(thread);\n      }\n    }\n  }\n}\n\nclass RedisClientReconcilerCoordinatorBackend implements ClientReconcilerCoordinatorBackend {\n  private readonly logger = getLoggerFor(this);\n  private readonly redis: Redis;\n  private readonly namespace: string;\n  private readonly heartbeatTtlMs: number;\n  private shuttingDown = false;\n\n  public constructor(options: { redisUrl: string; namespace?: string; heartbeatTtlMs: number }) {\n    this.namespace = options.namespace ?? 'xpod:coordination:';\n    this.heartbeatTtlMs = options.heartbeatTtlMs;\n    this.redis = new Redis(options.redisUrl, { lazyConnect: false });\n    attachRedisClientErrorHandler(this.redis, {\n      logger: this.logger,\n      label: 'ClientReconcilerCoordinator',\n      isShuttingDown: () => this.shuttingDown,\n    });\n  }\n\n  public async upsertClientCapability(capability: ClientCapability): Promise<ClientCapability> {\n    await this.redis.set(\n      this.clientStorageKey(capability.user, capability.clientId),\n      JSON.stringify(capability),\n      'PX',\n      this.heartbeatTtlMs,\n    );\n    return { ...capability, workspaces: [ ...capability.workspaces ] };\n  }\n\n  public async listClientCapabilities(user: string): Promise<ClientCapability[]> {\n    const keys = await this.scanKeys(`${this.clientStoragePrefix(user)}*`);\n    if (keys.length === 0) {\n      return [];\n    }\n    const raws = await this.redis.mget(keys);\n    return raws\n      .map((raw) => parseJson<ClientCapability>(raw))\n      .filter((client): client is ClientCapability => Boolean(client && client.user === user));\n  }\n\n  public async getLease(thread: string): Promise<ClientReconcilerLease | undefined> {\n    return parseJson<ClientReconcilerLease>(await this.redis.get(this.leaseStorageKey(thread)));\n  }\n\n  public async saveLease(lease: ClientReconcilerLease, ttlMs: number): Promise<ClientReconcilerLease> {\n    await this.redis.set(this.leaseStorageKey(lease.thread), JSON.stringify(lease), 'PX', ttlMs);\n    return { ...lease };\n  }\n\n  public async releaseLease(input: ReleaseClientReconcilerLeaseInput): Promise<boolean> {\n    const key = this.leaseStorageKey(input.thread);\n    const released = await this.redis.eval(\n      `local raw = redis.call('GET', KEYS[1])\n       if not raw then return 0 end\n       local value = cjson.decode(raw)\n       if value['ownerUser'] == ARGV[1] and value['ownerClientId'] == ARGV[2] then\n         return redis.call('DEL', KEYS[1])\n       end\n       return 0`,\n      1,\n      key,\n      input.ownerUser,\n      input.clientId,\n    );\n    return released === 1;\n  }\n\n  public async sweepExpired(_now: Date): Promise<void> {\n    // Redis key TTL owns expiry. No active sweep is required.\n  }\n\n  public async close(): Promise<void> {\n    this.shuttingDown = true;\n    await closeRedisClient(this.redis, {\n      logger: this.logger,\n      label: 'ClientReconcilerCoordinator',\n    });\n  }\n\n  private clientStoragePrefix(user: string): string {\n    return `${this.namespace}client:${hash(user)}:`;\n  }\n\n  private clientStorageKey(user: string, clientId: string): string {\n    return `${this.clientStoragePrefix(user)}${encodeURIComponent(clientId)}`;\n  }\n\n  private leaseStorageKey(thread: string): string {\n    return `${this.namespace}lease:${hash(thread)}`;\n  }\n\n  private async scanKeys(match: string): Promise<string[]> {\n    const keys: string[] = [];\n    let cursor = '0';\n    do {\n      const [ nextCursor, batch ] = await this.redis.scan(cursor, 'MATCH', match, 'COUNT', 100);\n      cursor = nextCursor;\n      keys.push(...batch);\n    } while (cursor !== '0');\n    return keys;\n  }\n}\n\nfunction normalizeClientKind(kind: unknown): ClientKind {\n  if (kind === 'cli' || kind === 'desktop' || kind === 'mobile' || kind === 'web') {\n    return kind;\n  }\n  throw new Error('kind must be one of cli, desktop, mobile, web');\n}\n\nfunction sanitizeWorkspaces(workspaces: unknown): string[] {\n  if (!Array.isArray(workspaces)) {\n    return [];\n  }\n  return Array.from(new Set(workspaces.filter((ref): ref is string => typeof ref === 'string' && ref.length > 0)));\n}\n\nfunction parseDateOrNow(value: unknown, now: Date): Date {\n  if (typeof value !== 'string') {\n    return now;\n  }\n  const parsed = Date.parse(value);\n  return Number.isFinite(parsed) ? new Date(parsed) : now;\n}\n\nfunction requireNonEmptyString(value: unknown, field: string): string {\n  if (typeof value !== 'string' || value.trim().length === 0) {\n    throw new Error(`${field} is required`);\n  }\n  return value.trim();\n}\n\nfunction clientKey(user: string, clientId: string): string {\n  return `${user}\\u0000${clientId}`;\n}\n\nfunction hash(value: string): string {\n  return createHash('sha256').update(value).digest('hex').slice(0, 32);\n}\n\nfunction parseJson<T>(raw: string | null): T | undefined {\n  if (!raw) {\n    return undefined;\n  }\n  try {\n    return JSON.parse(raw) as T;\n  } catch {\n    return undefined;\n  }\n}\n"]}

package/dist/api/reconciler/ClientReconcilerCoordinator.jsonld

@@ -0,0 +1,186 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator",
+      "@type": "Class",
+      "requireElement": "ClientReconcilerCoordinator",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator_options",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinatorOptions",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_now",
+          "memberFieldName": "now"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_heartbeatTtlMs",
+          "memberFieldName": "heartbeatTtlMs"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_leaseTtlMs",
+          "memberFieldName": "leaseTtlMs"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_backend",
+          "memberFieldName": "backend"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_upsertClientCapability",
+          "memberFieldName": "upsertClientCapability"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_listClientCapabilities",
+          "memberFieldName": "listClientCapabilities"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_activate",
+          "memberFieldName": "activate"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_getLease",
+          "memberFieldName": "getLease"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_releaseLease",
+          "memberFieldName": "releaseLease"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator__member_close",
+          "memberFieldName": "close"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinator_options"
+        }
+      ]
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinatorOptions",
+      "@type": "AbstractClass",
+      "requireElement": "ClientReconcilerCoordinatorOptions",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinatorOptions__member_redisUrl",
+          "memberFieldName": "redisUrl"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinatorOptions__member_now",
+          "memberFieldName": "now"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinatorOptions__member_heartbeatTtlMs",
+          "memberFieldName": "heartbeatTtlMs"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinatorOptions__member_leaseTtlMs",
+          "memberFieldName": "leaseTtlMs"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ClientReconcilerCoordinatorOptions__member_namespace",
+          "memberFieldName": "namespace"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput",
+      "@type": "AbstractClass",
+      "requireElement": "UpsertClientCapabilityInput",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput__member_clientId",
+          "memberFieldName": "clientId"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput__member_kind",
+          "memberFieldName": "kind"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput__member_user",
+          "memberFieldName": "user"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput__member_canCoordinateClientOwnedThread",
+          "memberFieldName": "canCoordinateClientOwnedThread"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput__member_canRunAgent",
+          "memberFieldName": "canRunAgent"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput__member_workspaces",
+          "memberFieldName": "workspaces"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#UpsertClientCapabilityInput__member_heartbeatAt",
+          "memberFieldName": "heartbeatAt"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ActivateClientReconcilerLeaseInput",
+      "@type": "AbstractClass",
+      "requireElement": "ActivateClientReconcilerLeaseInput",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ActivateClientReconcilerLeaseInput__member_thread",
+          "memberFieldName": "thread"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ActivateClientReconcilerLeaseInput__member_ownerUser",
+          "memberFieldName": "ownerUser"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ActivateClientReconcilerLeaseInput__member_requesterClientId",
+          "memberFieldName": "requesterClientId"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ReleaseClientReconcilerLeaseInput",
+      "@type": "AbstractClass",
+      "requireElement": "ReleaseClientReconcilerLeaseInput",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ReleaseClientReconcilerLeaseInput__member_thread",
+          "memberFieldName": "thread"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ReleaseClientReconcilerLeaseInput__member_ownerUser",
+          "memberFieldName": "ownerUser"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/ClientReconcilerCoordinator.jsonld#ReleaseClientReconcilerLeaseInput__member_clientId",
+          "memberFieldName": "clientId"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

package/dist/api/reconciler/ServerGroupReconcilerService.d.ts

@@ -0,0 +1,39 @@
+import { type ReconcilerOwner, type SharedWakeAgentJob } from './coordination';
+import { type WakeAgentQueue } from './WakeAgentQueue';
+export interface ReconcileGroupThreadMessageInput {
+    thread: string;
+    triggerMessage: string;
+    actor?: string;
+    role?: 'user' | 'assistant' | 'system' | string;
+    content?: string;
+    reconcilerOwner?: ReconcilerOwner;
+    mentions?: string[];
+    routeTargetAgent?: string;
+    participants?: string[];
+}
+export interface ReconcileGroupThreadMessageResult {
+    wakeJobs: SharedWakeAgentJob[];
+    inserted: number;
+    skippedReason?: string;
+}
+export interface ServerGroupReconcilerServiceOptions {
+    wakeQueue?: WakeAgentQueue;
+    redisUrl?: string;
+    now?: () => Date;
+}
+/**
+ * Protocol-independent group-room Reconciler.
+ *
+ * It decides only whether a group message should enqueue minimal WakeAgentJob
+ * records. It does not choose models, providers, workspaces, or tool placement,
+ * and it does not create a durable Reconciler Pod resource.
+ */
+export declare class ServerGroupReconcilerService {
+    private readonly wakeQueue;
+    private readonly now;
+    constructor(options?: ServerGroupReconcilerServiceOptions);
+    reconcileThreadMessage(input: ReconcileGroupThreadMessageInput): Promise<ReconcileGroupThreadMessageResult>;
+    listQueued(thread: string, agent?: string): Promise<SharedWakeAgentJob[]>;
+    close(): Promise<void>;
+}
+export declare function normalizeAgentUris(value: unknown): string[];

package/dist/api/reconciler/ServerGroupReconcilerService.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerGroupReconcilerService = void 0;
+exports.normalizeAgentUris = normalizeAgentUris;
+const coordination_1 = require("./coordination");
+const WakeAgentQueue_1 = require("./WakeAgentQueue");
+/**
+ * Protocol-independent group-room Reconciler.
+ *
+ * It decides only whether a group message should enqueue minimal WakeAgentJob
+ * records. It does not choose models, providers, workspaces, or tool placement,
+ * and it does not create a durable Reconciler Pod resource.
+ */
+class ServerGroupReconcilerService {
+    constructor(options = {}) {
+        this.wakeQueue = options.wakeQueue ?? (0, WakeAgentQueue_1.createWakeAgentQueue)({ redisUrl: options.redisUrl });
+        this.now = options.now ?? (() => new Date());
+    }
+    async reconcileThreadMessage(input) {
+        const reconcilerOwner = (0, coordination_1.normalizeReconcilerOwner)(input.reconcilerOwner, 'server');
+        if (reconcilerOwner !== 'server') {
+            return { wakeJobs: [], inserted: 0, skippedReason: 'not_server_reconciled' };
+        }
+        if (input.role && input.role !== 'user') {
+            return { wakeJobs: [], inserted: 0, skippedReason: 'not_user_message' };
+        }
+        const targets = selectWakeTargets({
+            mentions: input.mentions,
+            routeTargetAgent: input.routeTargetAgent,
+            participants: input.participants,
+        });
+        if (targets.length === 0) {
+            return { wakeJobs: [], inserted: 0, skippedReason: 'no_agent_selected' };
+        }
+        const createdAt = this.now().toISOString();
+        const jobs = targets.map(({ agent, reason }) => createWakeJob({
+            thread: input.thread,
+            triggerMessage: input.triggerMessage,
+            agent,
+            reason,
+            createdAt,
+        }));
+        let inserted = 0;
+        const enqueued = [];
+        for (const job of jobs) {
+            const result = await this.wakeQueue.enqueue(job);
+            if (result.inserted) {
+                inserted += 1;
+            }
+            enqueued.push(result.job);
+        }
+        return { wakeJobs: enqueued, inserted };
+    }
+    async listQueued(thread, agent) {
+        return this.wakeQueue.listQueued(thread, agent);
+    }
+    async close() {
+        await this.wakeQueue.close?.();
+    }
+}
+exports.ServerGroupReconcilerService = ServerGroupReconcilerService;
+function normalizeAgentUris(value) {
+    if (typeof value === 'string' && value.length > 0) {
+        return [value];
+    }
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return Array.from(new Set(value.filter((item) => typeof item === 'string' && item.length > 0)));
+}
+function selectWakeTargets(input) {
+    if (input.routeTargetAgent) {
+        return [{ agent: input.routeTargetAgent, reason: 'manual' }];
+    }
+    const participants = new Set(normalizeAgentUris(input.participants));
+    return normalizeAgentUris(input.mentions)
+        .filter((agent) => participants.size === 0 || participants.has(agent))
+        .map((agent) => ({ agent, reason: 'mention' }));
+}
+function createWakeJob(input) {
+    return {
+        id: (0, WakeAgentQueue_1.sharedWakeAgentJobId)(input),
+        thread: input.thread,
+        triggerMessage: input.triggerMessage,
+        agent: input.agent,
+        reason: input.reason,
+        status: 'queued',
+        createdAt: input.createdAt,
+    };
+}
+//# sourceMappingURL=ServerGroupReconcilerService.js.map

package/dist/api/reconciler/ServerGroupReconcilerService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerGroupReconcilerService.js","sourceRoot":"","sources":["../../../src/api/reconciler/ServerGroupReconcilerService.ts"],"names":[],"mappings":";;;AAqGA,gDAQC;AA7GD,iDAKwB;AACxB,qDAI0B;AA0B1B;;;;;;GAMG;AACH,MAAa,4BAA4B;IAIvC,YAAmB,UAA+C,EAAE;QAClE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAA,qCAAoB,EAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAEM,KAAK,CAAC,sBAAsB,CAAC,KAAuC;QACzE,MAAM,eAAe,GAAG,IAAA,uCAAwB,EAAC,KAAK,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;QAClF,IAAI,eAAe,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC;QAC/E,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACxC,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,aAAa,EAAE,kBAAkB,EAAE,CAAC;QAC1E,CAAC;QAED,MAAM,OAAO,GAAG,iBAAiB,CAAC;YAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,YAAY,EAAE,KAAK,CAAC,YAAY;SACjC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC;QAC3E,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC;YAC5D,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,KAAK;YACL,MAAM;YACN,SAAS;SACV,CAAC,CAAC,CAAC;QAEJ,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,MAAM,QAAQ,GAAyB,EAAE,CAAC;QAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACjD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpB,QAAQ,IAAI,CAAC,CAAC;YAChB,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAC1C,CAAC;IAEM,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,KAAc;QACpD,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IAEM,KAAK,CAAC,KAAK;QAChB,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;IACjC,CAAC;CACF;AAxDD,oEAwDC;AAED,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,CAAE,KAAK,CAAE,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,SAAS,iBAAiB,CAAC,KAI1B;IACC,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC3B,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,kBAAkB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;IACrE,OAAO,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC;SACtC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;SACrE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,aAAa,CAAC,KAMtB;IACC,OAAO;QACL,EAAE,EAAE,IAAA,qCAAoB,EAAC,KAAK,CAAC;QAC/B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAC;AACJ,CAAC","sourcesContent":["import {\n  normalizeReconcilerOwner,\n  type ReconcilerOwner,\n  type SharedWakeAgentJob,\n  type WakeAgentReason,\n} from './coordination';\nimport {\n  createWakeAgentQueue,\n  sharedWakeAgentJobId,\n  type WakeAgentQueue,\n} from './WakeAgentQueue';\n\nexport interface ReconcileGroupThreadMessageInput {\n  thread: string;\n  triggerMessage: string;\n  actor?: string;\n  role?: 'user' | 'assistant' | 'system' | string;\n  content?: string;\n  reconcilerOwner?: ReconcilerOwner;\n  mentions?: string[];\n  routeTargetAgent?: string;\n  participants?: string[];\n}\n\nexport interface ReconcileGroupThreadMessageResult {\n  wakeJobs: SharedWakeAgentJob[];\n  inserted: number;\n  skippedReason?: string;\n}\n\nexport interface ServerGroupReconcilerServiceOptions {\n  wakeQueue?: WakeAgentQueue;\n  redisUrl?: string;\n  now?: () => Date;\n}\n\n/**\n * Protocol-independent group-room Reconciler.\n *\n * It decides only whether a group message should enqueue minimal WakeAgentJob\n * records. It does not choose models, providers, workspaces, or tool placement,\n * and it does not create a durable Reconciler Pod resource.\n */\nexport class ServerGroupReconcilerService {\n  private readonly wakeQueue: WakeAgentQueue;\n  private readonly now: () => Date;\n\n  public constructor(options: ServerGroupReconcilerServiceOptions = {}) {\n    this.wakeQueue = options.wakeQueue ?? createWakeAgentQueue({ redisUrl: options.redisUrl });\n    this.now = options.now ?? (() => new Date());\n  }\n\n  public async reconcileThreadMessage(input: ReconcileGroupThreadMessageInput): Promise<ReconcileGroupThreadMessageResult> {\n    const reconcilerOwner = normalizeReconcilerOwner(input.reconcilerOwner, 'server');\n    if (reconcilerOwner !== 'server') {\n      return { wakeJobs: [], inserted: 0, skippedReason: 'not_server_reconciled' };\n    }\n    if (input.role && input.role !== 'user') {\n      return { wakeJobs: [], inserted: 0, skippedReason: 'not_user_message' };\n    }\n\n    const targets = selectWakeTargets({\n      mentions: input.mentions,\n      routeTargetAgent: input.routeTargetAgent,\n      participants: input.participants,\n    });\n    if (targets.length === 0) {\n      return { wakeJobs: [], inserted: 0, skippedReason: 'no_agent_selected' };\n    }\n\n    const createdAt = this.now().toISOString();\n    const jobs = targets.map(({ agent, reason }) => createWakeJob({\n      thread: input.thread,\n      triggerMessage: input.triggerMessage,\n      agent,\n      reason,\n      createdAt,\n    }));\n\n    let inserted = 0;\n    const enqueued: SharedWakeAgentJob[] = [];\n    for (const job of jobs) {\n      const result = await this.wakeQueue.enqueue(job);\n      if (result.inserted) {\n        inserted += 1;\n      }\n      enqueued.push(result.job);\n    }\n\n    return { wakeJobs: enqueued, inserted };\n  }\n\n  public async listQueued(thread: string, agent?: string): Promise<SharedWakeAgentJob[]> {\n    return this.wakeQueue.listQueued(thread, agent);\n  }\n\n  public async close(): Promise<void> {\n    await this.wakeQueue.close?.();\n  }\n}\n\nexport function normalizeAgentUris(value: unknown): string[] {\n  if (typeof value === 'string' && value.length > 0) {\n    return [ value ];\n  }\n  if (!Array.isArray(value)) {\n    return [];\n  }\n  return Array.from(new Set(value.filter((item): item is string => typeof item === 'string' && item.length > 0)));\n}\n\nfunction selectWakeTargets(input: {\n  mentions?: string[];\n  routeTargetAgent?: string;\n  participants?: string[];\n}): Array<{ agent: string; reason: WakeAgentReason }> {\n  if (input.routeTargetAgent) {\n    return [{ agent: input.routeTargetAgent, reason: 'manual' }];\n  }\n\n  const participants = new Set(normalizeAgentUris(input.participants));\n  return normalizeAgentUris(input.mentions)\n    .filter((agent) => participants.size === 0 || participants.has(agent))\n    .map((agent) => ({ agent, reason: 'mention' }));\n}\n\nfunction createWakeJob(input: {\n  thread: string;\n  triggerMessage: string;\n  agent: string;\n  reason: WakeAgentReason;\n  createdAt: string;\n}): SharedWakeAgentJob {\n  return {\n    id: sharedWakeAgentJobId(input),\n    thread: input.thread,\n    triggerMessage: input.triggerMessage,\n    agent: input.agent,\n    reason: input.reason,\n    status: 'queued',\n    createdAt: input.createdAt,\n  };\n}\n"]}