agent-relay-server 0.33.0 → 0.34.0

package/src/db/agents.ts

@@ -0,0 +1,551 @@
+import { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { parseJson } from "../utils";
+import { isLiveIsolatedWorkspace } from "../workspace-phase";
+import {
+  CONTRACT_REQUIREMENTS,
+  contractCompatibility,
+  parseRuntimeCapabilities,
+  parseRuntimeContracts,
+  parseRuntimePackage,
+  type RuntimeContracts,
+} from "../contracts";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { matchAgents } from "../agent-ref";
+import { evaluatePoolBindings, expectedChannelAgentId, upsertChannelForAgent } from "./channels.ts";
+import { ValidationError, getDb } from "./connection.ts";
+import { rowToAgent, rowToContextSnapshot } from "./mappers.ts";
+import { closeOpenPairsForAgent } from "./pairs.ts";
+import { TASK_SELECT, insertTaskEvent } from "./tasks.ts";
+import { electWorkspaceStewards, electWorkspaceStewardsForAgent } from "./workspaces.ts";
+import type {
+  AgentCard,
+  ActivityEvent,
+  ActivityEventInput,
+  AgentKind,
+  AgentSessionGuard,
+  Artifact,
+  ArtifactBlob,
+  ArtifactKind,
+  ArtifactLink,
+  ArtifactSensitivity,
+  ArtifactVisibility,
+  AttachmentRef,
+  ChannelBinding,
+  ChannelBindingMode,
+  ChannelRouteTarget,
+  ChatHistoryImport,
+  ChatHistoryImportEntry,
+  ChannelSummary,
+  ChannelTargetHealth,
+  CreatePairInput,
+  HealthCheck,
+  HealthReport,
+  ManagedAgent,
+  ManagedSessionExitDiagnostics,
+  Message,
+  MessageDeliveryAttempt,
+  MessageDeliveryStatus,
+  Orchestrator,
+  OrchestratorHealth,
+  OrchestratorRuntimeInput,
+  OrchestratorStatus,
+  OrchestratorUpgradeState,
+  PairActionInput,
+  PairMessageInput,
+  PairSession,
+  PairStatus,
+  RegisterAgentInput,
+  ReplyObligation,
+  RegisterOrchestratorInput,
+  SendMessageInput,
+  PollQuery,
+  SpawnApprovalMode,
+  SpawnProvider,
+  Task,
+  TaskEvent,
+  TaskSeverity,
+  TaskStatus,
+  IntegrationEventInput,
+  IntegrationSummary,
+  IntegrationTaskStats,
+  InboxDraft,
+  InboxState,
+  InboxThreadState,
+  ContextSnapshot,
+  ContextState,
+  ProviderCapabilities,
+  TaskStatusInput,
+  WorkspaceMetadata,
+  WorkspaceRecord,
+  WorkspaceStatus,
+} from "../types";
+
+const CONTEXT_SNAPSHOT_DEBOUNCE_MS = 60_000;
+
+export function parseStringArray(raw: string): string[] {
+  const parsed = parseJson<unknown>(raw, []);
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((value): value is string => typeof value === "string");
+}
+
+export function normalizeTags(tags: string[] | undefined): string[] {
+  return [...new Set((tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
+}
+
+export function inferAgentKind(input: Pick<RegisterAgentInput, "id" | "kind" | "tags" | "capabilities" | "meta">): AgentKind {
+  if (input.kind) return input.kind;
+  if (input.id === "user") return "user";
+  if (input.id === "system") return "system";
+  const metaKind = stringValue(input.meta?.kind);
+  if (metaKind === "channel" || metaKind === "communication-channel") return "channel";
+  if (metaKind === "orchestrator") return "orchestrator";
+  if ((input.tags ?? []).includes("channel") || (input.capabilities ?? []).includes("channel")) return "channel";
+  return "provider";
+}
+
+export function inferProviderTag(input: RegisterAgentInput): "claude" | "codex" | undefined {
+  if (inferAgentKind(input) !== "provider") return undefined;
+  const meta = input.meta ?? {};
+  const values = [
+    input.id,
+    input.name,
+    input.rig,
+    ...(input.tags ?? []),
+    stringValue(meta.provider),
+    stringValue(meta.client),
+    stringValue(meta.runtime),
+    stringValue(meta.agentType),
+  ].filter((value): value is string => typeof value === "string");
+
+  if (values.some((value) => value.toLowerCase().includes("codex"))) return "codex";
+  if (values.some((value) => value.toLowerCase().includes("claude"))) return "claude";
+
+  // Older Claude hooks did not always send an explicit provider tag, but did
+  // send Claude-style approval metadata. Codex also sends approvalMode, so this
+  // fallback only runs after Codex signals have been ruled out.
+  if (Object.prototype.hasOwnProperty.call(meta, "approvalMode")) return "claude";
+  return undefined;
+}
+
+export function tagsWithProvider(input: RegisterAgentInput): string[] {
+  const tags = normalizeTags(input.tags);
+  const provider = inferProviderTag(input);
+  if (!provider || tags.includes(provider)) return tags;
+  return [provider, ...tags];
+}
+
+
+export function upsertAgent(input: RegisterAgentInput): AgentCard {
+  const now = Date.now();
+  const kind = inferAgentKind(input);
+  if (kind === "channel") {
+    const expectedId = expectedChannelAgentId(input);
+    if (input.id !== expectedId) {
+      throw new ValidationError(`channel agent id must be canonical: ${expectedId}`);
+    }
+  }
+  const tags = tagsWithProvider(input);
+  // Preserve the existing label across re-registrations unless the caller
+  // explicitly sends one (including null to clear).
+  const labelProvided = Object.prototype.hasOwnProperty.call(input, "label");
+  const readyProvided = Object.prototype.hasOwnProperty.call(input, "ready");
+  const instanceProvided = Boolean(input.instanceId);
+  const stmt = getDb().query(`
+    INSERT INTO agents (id, name, kind, label, tags, machine, rig, capabilities, ready, status, instance_id, epoch, provider_capabilities, context_state, meta, spawned_by, last_seen, created_at)
+    VALUES ($id, $name, $kind, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $providerCapabilities, $contextState, $meta, $spawnedBy, $now, $now)
+    ON CONFLICT(id) DO UPDATE SET
+      name = $name,
+      kind = $kind,
+      label = CASE WHEN $labelProvided = 1 THEN $label ELSE agents.label END,
+      tags = $tags,
+      machine = coalesce($machine, agents.machine),
+      rig = coalesce($rig, agents.rig),
+      capabilities = $capabilities,
+      ready = CASE WHEN $readyProvided = 1 THEN $ready ELSE agents.ready END,
+      status = $status,
+      instance_id = CASE WHEN $instanceProvided = 1 THEN $instanceId ELSE agents.instance_id END,
+      epoch = CASE
+        WHEN $instanceProvided = 1 AND (agents.instance_id IS NULL OR agents.instance_id <> $instanceId) THEN agents.epoch + 1
+        ELSE agents.epoch
+      END,
+      provider_capabilities = coalesce($providerCapabilities, agents.provider_capabilities),
+      context_state = coalesce($contextState, agents.context_state),
+      meta = $meta,
+      spawned_by = coalesce($spawnedBy, agents.spawned_by),
+      last_seen = $now
+  `);
+
+  stmt.run({
+    $id: input.id,
+    $name: input.name,
+    $kind: kind,
+    $label: input.label ?? null,
+    $labelProvided: labelProvided ? 1 : 0,
+    $tags: JSON.stringify(tags),
+    $machine: input.machine ?? null,
+    $rig: input.rig ?? null,
+    $capabilities: JSON.stringify(input.capabilities ?? []),
+    $ready: input.ready ? 1 : 0,
+    $readyProvided: readyProvided ? 1 : 0,
+    $status: input.status ?? "idle",
+    $instanceId: input.instanceId ?? null,
+    $instanceProvided: instanceProvided ? 1 : 0,
+    $initialEpoch: instanceProvided ? 1 : 0,
+    $providerCapabilities: input.providerCapabilities ? JSON.stringify(input.providerCapabilities) : null,
+    $contextState: input.context ? JSON.stringify(input.context) : null,
+    $meta: JSON.stringify(input.meta ?? {}),
+    $spawnedBy: input.spawnedBy ?? null,
+    $now: now,
+  });
+  if (input.context) recordContextSnapshot(input.id, input.context, now);
+
+  const agent = getAgent(input.id)!;
+  if (agent.kind === "channel") upsertChannelForAgent(agent);
+  evaluatePoolBindings();
+  // A (re)joining agent may revive a dormant repo steward — re-elect for the
+  // repos it owns live workspaces in (issue #157, steward survives offline gap).
+  if (agent.status !== "offline") electWorkspaceStewardsForAgent(agent.id);
+  return agent;
+}
+
+export function validateAgentSession(id: string, guard?: AgentSessionGuard): { ok: boolean; error?: string } {
+  if (!guard || (!guard.instanceId && guard.epoch === undefined)) return { ok: true };
+  const agent = getAgent(id);
+  if (!agent) return { ok: false, error: "agent not found" };
+  if (guard.instanceId && agent.instanceId !== guard.instanceId) {
+    return { ok: false, error: "stale agent instance" };
+  }
+  if (guard.epoch !== undefined && agent.epoch !== guard.epoch) {
+    return { ok: false, error: "stale agent instance" };
+  }
+  return { ok: true };
+}
+
+export function setLabel(id: string, label: string | null): boolean {
+  const normalized = label && label.trim() ? label.trim() : null;
+  return (
+    getDb().query("UPDATE agents SET label = ? WHERE id = ?").run(normalized, id).changes > 0
+  );
+}
+
+export function setTags(id: string, tags: string[]): AgentCard | null {
+  const normalized = [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
+  const result = getDb().query("UPDATE agents SET tags = ?, last_seen = ? WHERE id = ?").run(JSON.stringify(normalized), Date.now(), id);
+  return result.changes > 0 ? getAgent(id) : null;
+}
+
+export function getAgent(id: string): AgentCard | null {
+  const row = getDb().query("SELECT * FROM agents WHERE id = ?").get(id) as any;
+  return row ? rowToAgent(row) : null;
+}
+
+export function listAgents(filter?: {
+  tag?: string;
+  machine?: string;
+  status?: string;
+}): AgentCard[] {
+  let sql = "SELECT * FROM agents WHERE 1=1";
+  const params: any[] = [];
+
+  if (filter?.tag) {
+    sql += " AND EXISTS (SELECT 1 FROM json_each(tags) WHERE value = ?)";
+    params.push(filter.tag);
+  }
+  if (filter?.machine) {
+    sql += " AND machine = ?";
+    params.push(filter.machine);
+  }
+  if (filter?.status) {
+    sql += " AND status = ?";
+    params.push(filter.status);
+  }
+
+  sql += " ORDER BY last_seen DESC";
+  return (getDb().query(sql).all(...params) as any[]).map(rowToAgent);
+}
+
+
+export function countLiveSpawnedAgents(parentId: string, now: number = Date.now()): number {
+  const row = getDb().query(
+    "SELECT count(*) AS n FROM agents WHERE spawned_by = ? AND status NOT IN ('offline', 'stale') AND ready = 1 AND last_seen > ?",
+  ).get(parentId, now - STALE_TTL_MS) as { n: number };
+  return row.n;
+}
+
+export function setStatus(id: string, status: AgentCard["status"], guard?: AgentSessionGuard): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
+  const now = Date.now();
+  const ready = status === "offline" ? 0 : undefined;
+  const sql = ready === 0
+    ? "UPDATE agents SET status = ?, ready = 0, last_seen = ? WHERE id = ?"
+    : "UPDATE agents SET status = ?, last_seen = ? WHERE id = ?";
+  const changed = getDb().query(sql).run(status, now, id).changes > 0;
+  if (changed && status === "offline") closeOpenPairsForAgent(id, now);
+  if (changed && status === "offline") electWorkspaceStewards();
+  return changed;
+}
+
+export function markReady(id: string, ready: boolean, guard?: AgentSessionGuard): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
+  const now = Date.now();
+  return (
+    getDb()
+      .query("UPDATE agents SET ready = ?, last_seen = ? WHERE id = ?")
+      .run(ready ? 1 : 0, now, id).changes > 0
+  );
+}
+
+export function mergeAgentMeta(id: string, meta: Record<string, unknown>, guard?: AgentSessionGuard): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
+  const agent = getAgent(id);
+  if (!agent) return false;
+  const merged = { ...(agent.meta ?? {}), ...meta };
+  const result = getDb()
+    .query("UPDATE agents SET meta = ?, last_seen = ? WHERE id = ?")
+    .run(JSON.stringify(merged), Date.now(), id);
+  return result.changes > 0;
+}
+
+export function recordAgentExitDiagnostics(id: string, diagnostics: ManagedSessionExitDiagnostics): AgentCard | null {
+  const agent = getAgent(id);
+  if (!agent) return null;
+  const now = Date.now();
+  const merged = {
+    ...(agent.meta ?? {}),
+    lastError: diagnostics.lastError,
+    lastExit: diagnostics,
+    lastExitAt: diagnostics.detectedAt || now,
+  };
+  const result = getDb()
+    .query("UPDATE agents SET status = 'offline', ready = 0, meta = ?, last_seen = ? WHERE id = ?")
+    .run(JSON.stringify(merged), now, id);
+  if (result.changes <= 0) return null;
+  closeOpenPairsForAgent(id, now);
+  return getAgent(id);
+}
+
+export function heartbeat(
+  id: string,
+  guard?: AgentSessionGuard,
+  runtime?: { providerCapabilities?: ProviderCapabilities; context?: ContextState },
+): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
+  const now = Date.now();
+  if (runtime?.providerCapabilities || runtime?.context) {
+    const result = getDb()
+      .query(`
+        UPDATE agents SET
+          last_seen = ?,
+          status = CASE WHEN status = 'offline' THEN 'idle' ELSE status END,
+          provider_capabilities = coalesce(?, provider_capabilities),
+          context_state = coalesce(?, context_state)
+        WHERE id = ?
+      `)
+      .run(
+        now,
+        runtime.providerCapabilities ? JSON.stringify(runtime.providerCapabilities) : null,
+        runtime.context ? JSON.stringify(runtime.context) : null,
+        id,
+      );
+    if (result.changes > 0 && runtime.context) recordContextSnapshot(id, runtime.context, now);
+    return result.changes > 0;
+  }
+  const result = getDb()
+    .query("UPDATE agents SET last_seen = ?, status = CASE WHEN status = 'offline' THEN 'idle' ELSE status END WHERE id = ?")
+    .run(now, id);
+  return result.changes > 0;
+}
+
+export function listContextSnapshots(agentId: string, options: { since?: number; limit?: number } = {}): ContextSnapshot[] {
+  const limit = Math.max(1, Math.min(options.limit ?? 288, 1000));
+  const params: any[] = [agentId];
+  let sql = "SELECT * FROM context_snapshots WHERE agent_id = ?";
+  if (options.since !== undefined) {
+    sql += " AND captured_at >= ?";
+    params.push(options.since);
+  }
+  sql += " ORDER BY captured_at ASC LIMIT ?";
+  params.push(limit);
+  return (getDb().query(sql).all(...params) as any[]).map(rowToContextSnapshot);
+}
+
+export function pruneContextSnapshots(agentId?: string, olderThan = Date.now() - DAY_MS): number {
+  const result = agentId
+    ? getDb().query("DELETE FROM context_snapshots WHERE agent_id = ? AND captured_at < ?").run(agentId, olderThan)
+    : getDb().query("DELETE FROM context_snapshots WHERE captured_at < ?").run(olderThan);
+  return result.changes;
+}
+
+export function recordContextSnapshot(agentId: string, context: ContextState, now: number): void {
+  const latest = getDb()
+    .query("SELECT captured_at FROM context_snapshots WHERE agent_id = ? ORDER BY captured_at DESC LIMIT 1")
+    .get(agentId) as { captured_at: number } | undefined;
+  if (latest && latest.captured_at > now - CONTEXT_SNAPSHOT_DEBOUNCE_MS) return;
+
+  getDb().query(`
+    INSERT INTO context_snapshots (
+      agent_id,
+      utilization,
+      lifecycle_state,
+      tokens_used,
+      tokens_max,
+      source,
+      confidence,
+      context_state,
+      captured_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    agentId,
+    context.utilization,
+    context.lifecycleState,
+    context.tokensUsed ?? null,
+    context.tokensMax ?? null,
+    context.source,
+    context.confidence,
+    JSON.stringify(context),
+    now,
+  );
+  pruneContextSnapshots(agentId, now - DAY_MS);
+}
+
+
+export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
+  const now = Date.now();
+  const cutoff = now - ttlMs;
+  getDb().query("UPDATE agents SET last_seen = ? WHERE id IN ('user', 'system')").run(now);
+  const rows = getDb()
+    .query(
+      "UPDATE agents SET status = 'offline', ready = 0 WHERE status NOT IN ('offline', 'stale') AND last_seen < ? AND id NOT IN ('user', 'system') RETURNING id"
+    )
+    .all(cutoff) as any[];
+  for (const row of rows) {
+    revokeRuntimeTokensForAgent(row.id, now);
+    closeOpenPairsForAgent(row.id, now);
+  }
+  return rows.map((r: any) => r.id);
+}
+
+// On-demand automation tasks (targetMode=on_demand_agent) are bound to a single
+// ephemeral agent spawned just for that task. When that agent's claim is released —
+// clean shutdown, prune, lease expiry, or orphan-grace — the task must NOT return to
+// the claimable pool: its target is a unique `label:automation-…` that no other agent
+// will ever match, so a re-opened task lingers forever as an orphaned claim. Resolve
+// those as done instead; automation reconcile then settles the run as succeeded.
+// Run this BEFORE the generic re-open UPDATE at each release site, with the same WHERE
+// condition: it flips matching single-target tasks to 'done', which the subsequent
+// re-open (gated on status IN claimed/in_progress/blocked/orphaned) then skips.
+export function settleSingleTargetOnDemandTasks(condition: string, params: any[], now: number, reason: string): void {
+  const selectSql = `${TASK_SELECT} WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`;
+  const rows = getDb().query(selectSql).all(...params) as any[];
+  if (rows.length === 0) return;
+  getDb().query(
+    `UPDATE tasks SET status = 'done', claim_expires_at = NULL, updated_at = ?, last_seen_at = ? WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`
+  ).run(now, now, ...params);
+  for (const row of rows) {
+    insertTaskEvent(row.id, {
+      source: "agent-relay",
+      type: "task.auto-completed",
+      severity: row.severity,
+      title: "On-demand task auto-resolved",
+      body: `On-demand agent ${row.claimed_by ?? "(unknown)"} exited (${reason}); task resolved so it does not orphan`,
+      metadata: { agentId: row.claimed_by, reason, completedBy: "relay" },
+    }, now);
+  }
+}
+
+export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
+  const cutoff = Date.now() - maxOfflineMs;
+  return getDb().transaction(() => {
+    const rows = getDb()
+      .query(
+        "SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system')"
+      )
+      .all(cutoff) as any[];
+    if (rows.length === 0) return [];
+    const now = Date.now();
+
+    // Release claims held by pruned agents so work becomes claimable again.
+    getDb()
+      .query(
+        "UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system'))"
+      )
+      .run(cutoff);
+
+    const offlineClaimCondition = "claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system'))";
+    settleSingleTargetOnDemandTasks(offlineClaimCondition, [cutoff], now, "agent-pruned");
+
+    getDb()
+      .query(
+        `UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE ${offlineClaimCondition} AND status IN ('claimed', 'in_progress', 'blocked')`
+      )
+      .run(now, cutoff);
+
+    for (const row of rows) {
+      revokeRuntimeTokensForAgent(row.id, now);
+      closeOpenPairsForAgent(row.id, now);
+    }
+
+    getDb()
+      .query(
+        "DELETE FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system')"
+      )
+      .run(cutoff);
+
+    return rows.map((r: any) => r.id);
+  })();
+}
+
+export function deleteAgent(id: string): { ok: boolean; error?: string } {
+  if (id === "user" || id === "system") {
+    return { ok: false, error: "built-in agent cannot be deleted" };
+  }
+  const deleted = getDb().transaction(() => {
+    // Release any claims held by this agent so the tasks become claimable again.
+    // from_agent is left intact as historical record.
+    const now = Date.now();
+    getDb().query("UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by = ?").run(id);
+    settleSingleTargetOnDemandTasks("claimed_by = ?", [id], now, "agent-removed");
+    getDb().query("UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE claimed_by = ? AND status IN ('claimed', 'in_progress', 'blocked')").run(now, id);
+    revokeRuntimeTokensForAgent(id, now);
+    closeOpenPairsForAgent(id, now);
+    return getDb().query("DELETE FROM agents WHERE id = ?").run(id).changes > 0;
+  })();
+  return deleted ? { ok: true } : { ok: false, error: "agent not found" };
+}
+
+export function revokeRuntimeTokensForAgent(agentId: string, now = Date.now()): string[] {
+  const row = getDb().query("SELECT meta FROM agents WHERE id = ?").get(agentId) as { meta?: string } | undefined;
+  const jtis = runtimeTokenJtisFromMeta(parseJson(row?.meta ?? "{}", {}));
+  if (jtis.length === 0) return [];
+  const revokedAt = Math.floor(now / 1000);
+  const placeholders = jtis.map(() => "?").join(",");
+  const rows = getDb().query(`
+    UPDATE tokens
+    SET revoked_at = ?
+    WHERE revoked_at IS NULL
+      AND role = 'provider'
+      AND profile_id IN ('provider-agent', 'provider-interactive', 'provider-child')
+      AND jti IN (${placeholders})
+    RETURNING jti
+  `).all(revokedAt, ...jtis) as Array<{ jti: string }>;
+  return rows.map((item) => item.jti);
+}
+
+export function runtimeTokenJtisFromMeta(meta: Record<string, unknown>): string[] {
+  const jtis = new Set<string>();
+  const auth = isRecord(meta.auth) ? meta.auth : undefined;
+  const direct = typeof auth?.jti === "string" ? auth.jti : typeof meta.runtimeTokenJti === "string" ? meta.runtimeTokenJti : undefined;
+  if (direct) jtis.add(direct);
+  const extra = Array.isArray(auth?.jtis) ? auth.jtis : Array.isArray(meta.runtimeTokenJtis) ? meta.runtimeTokenJtis : [];
+  for (const item of extra) {
+    if (typeof item === "string") jtis.add(item);
+  }
+  return [...jtis];
+}
+
+// --- Tasks ---
+